OovAide Design

Last update: Oct 23, 2015
BlueGriffon was used to edit this design document.
Inkscape may be used to edit .svg diagram files from OovAide.

Description
Components
Libraries
1. OovCommon
2. OovGuiCommon
Build Processing
1. Analysis Mode
2. Build Mode
Multitasking

Description

This design document describes the oovaide program. It also contains examples of the diagrams that have been produced with the program, and it contains descriptions of the diagrams.

Components

The following are components used as part of the OovAide project.

Component	Description
mingw-w64	This library is used only on Windows
llvm	This is the LLVM project libraries that support CLang for C++ parsing
gtk+-3.0	GTK is a library used for graphics display / GUI
oovCommon	A library to share common code for all tools
oovGuiCommon	A library to share common GUI code for GUI tools
OovCppParser	A command line tool that parses a C++ file and produces an XML output file.
OovJavaParser	A command line tool that parses a Java file and produces an XML output file.
OovBuilder	A command line tool that recursively parses a directory to find C++ files, and runs the Oov CPP parser on each file. Keeps track of source file modification times so that only modified source files are parsed. This component calls the OovCppParser component to extract information from source files.
oovaide	Top level GUI that runs the OovBuilder to parse source files. Then it displays the information as class and sequence diagrams. This component calls the OovBuilder and OovEdit programs.
OovEdit	A simple C++ or Java editor
OovCMaker	A command line tool that creates CMake files from a project.
OovCovInstr	A command line tool that generates code test coverage instrumentation

Diagram Notes:

This is a standard UML component dependency diagram.
The arrow points to the supplier, and the consumer is at the other end of the dashed line.
The External and StaticLib components are sources and binaries. The Program components are executables.
The top three components (mingw-w64, llvm, and gtk+-3.0) are used by OovAide project, but are provided externally.

OovCppParser

The OovCppParser is a command line tool based on the CLang LLVM C++ parser. It is used to parse the C++ source files and saves drawing information in one XMI file for each C++ source file. The include dependencies are saved in a single file for all source files in a project. There is optional duplicate code detection that is saved in a file for each C++ source file.

Class	Description
CppParser	This class parses a single source file and saves data in the ModelData.
ParserModelData	Provides the interface to the object model, which is the representation of the class and method relationships, and other information kept in the model.
ModelWriter	The ModelWriter reads the ModelData and writes the parsed C++ information to an output file.
IncDirDependencyMap	The CppParser gets include dependencies from the source files, and saves them to a file.
SwitchContexts	Saves information while compiling switch statements.
DupHashFile	Creates a hash of code tokens for duplicate code detection.
SharedFile	Provides synchronization for the include file that is updated and read by multiple processes.
CXStringDisposer	This is a utility class that disposes strings allocated by CLang.
SplitType	This class helps to extract type information.
Model...	The other model classes are described in the oovCommon library.

Diagram Notes:

The CppParser owns/contains (controls the lifetime of) the ModelData as seen by the filled in aggregation diamond connection. The CppParse modifies the Model objects from the oovCommon library since there is no unidirectional V symbol.
The ModelWriter only refers (has a pointer of reference) to the ModelData as seen by the non-filled aggregation diamond connection. The V symbol indicates that this is a const references, so ModelData is not modified by the ModelWriter.
Some CppParser functions use the CXStringDisposer as seen by the circle connection.
Some CppParser function parameters pass the SplitType class as seen by the double circle connection.
All aggregation members are private as seen by the filled circle aggregation connections.

After the file is parsed into the ModelData, then it is written by the ModelWriter.

The ModelWriter reads parts of the model and writes various model objects to the XML file. See the oovCommon library for the model objects descriptions.

Diagram Notes:

Note that all Model references are const relationships.

OovJavaParser

The OovJavaParser is a command line tool based on the Java parser. It is used to parse the Java source files and saves drawing information in one XMI file for each Java source file.There is optional duplicate code detection that is saved in a file for each Java source file.

The top level oovJavaParser program objects are shown below.

The part of the oovJavaParser program responsible for parsing is shown below.

Class	Description
parser.Parser	This class gets the Java compiler, initiates the ParserTreeVisitor and runs the scan on the Java source file to collect data into the class model.
parser.ParserTreeVisitor	This class overrides many of the visitor functions to fill the model with data.

The following portion diagram shows the visitor call tree, and which methods use which member variables. The visitMethod function uses the currentClass variable to add a method to the class. The statement and method functions update the currentMethod variable. The visit functions are virtual functions that are called while processing the Java file.

Since the Java parser is written in Java, the object model classes from the C++ code cannot be used. A separate set of object model classes were created and are used to write the analysis files. Once the oovaide program reads the objects, they are read into the C++ model classes.

Class	Description
parser.Parser	This class parses the Java source and fills the class model.
model.ModelData	This class contains the model types (classes)
model.ModelType	A ModelType is all of the information to store a class, and the inheritance relationships from other supplier classes. This model is different from the C++ model since there is no need to search type relations in order to save the file information.
model.ModelMethod	This class a single method for a class. A method has parameters and statements.
model.ModelStatement	Only statements needed for sequence and relationship information are stored. This includes conditional expressions, calls, and variable references.
model.ModelTypeRef	A type reference is a reference to a type, and associated identifier name.
model.ModelTypeRelation	This is for storing inheritance relationships.

OovBuilder

OovBuilder is a command line tool. The oovaide program invokes the OovBuilder from the command line. The OovBuilder works in two modes. For detailed information on processing, see OovAide Build Design.

Analysis Mode - To extract drawing information, OovBuilder recursively parses a directory to find C++ and Java files, and runs the OovCppParser or OovJavaParser on each file, and saves the information in files. It keeps track of source file modification times so that only newly modified source files are parsed.
Build Mode - OovBuilder builds a project including mutliple libraries and executables. After the user has defined what each component is, the user can use the OovBuilder to build each component.

The command line synopsis is:

oovBuilder project_directory [-bv][-cfg-<config>][-mode-<mode>]

Switch	Description
-bv	Verbose
-cfg	Specifies the build configuration. For example -cfg-Release will use the Release configuration to build the project.
-mode	Specifies the mode. The modes are analyze, build, cov-instr, cov-build, and cov-stats. The cov arguments are for code test coverage. Analyze only compiles for analysis information, while build compiles, build libraries and executables.

The ComponentFinder runs in both modes to discover the components determined from the directory structure. The ComponentFinder runs first so that all source and header files are discovered. The ComponentBuilder uses the information from the ComponentTypesFile in the ComponentFinder to determine the type of components to build. Depending on the component types, the correct object, library and executable files are built depending on dates of files.

Building object files uses the OovCppParser to create the include dependencies. Include dependency order is used during the build.
Building libraries will create ObjSymbols. Symbols are also created for external project libraries.
Building executables or shared libraries uses the ObjSymbols to determine the link order for libraries. The include dependencies are used to determine which libraries need to be linked into an executable.

Class	Description
ComponentFinder	Scans project and external directories for include headers and libraries.
ComponentBuilder	This builds object, library and executable files.
srcFileParser	Runs the OovCppParser component to produce analysis information for each source file found. The OovCppParser component produces the drawing XMI files and include dependencies.
VerboseDumer	This provides a log for dumping progress information.
Packages	This provides information about external packages to the main source project
Project	This mainly provides directory information about the project
dirRecurser	This class recursively finds files, and calls the virtual processFile function for each file found.

Diagram Notes:

The srcFileParser inherits from the dirRecursor to override the processFile function. This is shown as the arrow symbol. The open circles means that the inheritance relationship is public.

ComponentFinder

The ComponentFinder is a class within the OovBuilder program. The ComponentFinder searches the directories for C++ or Java source and header files. A component is the same as a directory, so each ScannedComponent contains all of the source and include files that is in a directory. All of the scanned component information is saved in a file.

Class	Description
ComponentFinder	Scans project and external directories for include headers and libraries.
dirRecurser	This class recursively finds files, and calls the virtual processFile function for each file found.
ScannedComponentsInfo	This is information kept during the scan.
ComponentsFile	This saves the include and exclude search directories for the components
ComponentTypesFile	This saves the names of the components and the component types.

ComponentBuilder

The ComponentBuilder builds the components including object, library and executable components.

Class	Description
ComponentBuilder	This builds object, library and executable files.
ComponentFinder	Scans project and external directories for include headers and libraries.
ObjSymbols	This parses library directories for symbols. It produces a sorted list of libraries.
ToolPathFile	This keeps paths to tools.
ComponentPkgDeps	Keeps the dependencies between components. These are generated from the include dependencies.
IncDirDependencyMapReader	Reads include dependencies from the include dependencies file that was created by OovCppParser.

Oovaide

The oovaide program displays many types of diagrams and analysis information, and provides the main working area for a project.

Oovaide GUI

The GUI objects are objects that display information on screens. Some of the GUI objects are shown below.

Class	Description
oovGui	This is the top level class for the oovaide component.
Context	The context determines which lists are displayed to edit a drawing. It inherits from the JournalListener so that the journal can cause the GUI to update the class and operation list when a class or operation has been selected from any diagram.
OovProject	This keeps all project related data. Oovaide only works on a single project at a time. The project keeps the data model for the class relations.
Journal	This keeps a collection of journal records. Each record is a diagram that has been edited.
JournalListener	Allows the journal to indicate that a class or operation should be displayed.
ProjectStatus	This keeps track of whether the background process is busy. The menu updates based on this status.
WindowBuildListener	The background processing sends standard output to this class, which displayes the progress results in an output window.
WindowProjectStatusListener	This provides a dialog to show task busy progress.
...List	There are lists for classes, operations, zone diagrams, etc.

OovProject

The oovaide program keeps all of a projects information in the OovProject class.

Class	Description
ThreadedWorkBackgroundQueue	All of the analysis files are loaded on a background thread.
IncDirDependencyMapReader	This reads all of the include dependencies.
XmlParser	This provides an extremely simple XML parser.
XmiParser	The analysis files are in something like a UML XMI file format. This reads and resolves the relationships, and puts the information into the ModelData.
ProjectStatus	This keeps track of whether a project is being loaded, and when it is completely loaded.

Class Diagrams

The different diagrams (Class, Sequence, etc.) generally follow a common pattern.

Class	Description
View	Provides the GUI.
Graph	Contains the nodes and edges. Does not refer to the Graph or Drawer.
Drawer	Refers to the Graph, but not the Diagram. Cannot modify the Graph.
Diagram	Owns (controls the lifetime of) the Graph, and modifies the Graph, and refers to the Drawer when drawing needs to be performed.

The ClassDiagramView related classes provide the GUI for the class diagrams, and are shown below.

ClassDiagram Diagram

Class	Description
ClassDiagramView	This provides the display and input handling.
GtkCairoContext	This the cairo drawing interface.
NullDrawer	This provides a null drawer that is used for calculating sizes.

The ClassDiagram related classes draw class diagrams, and are shown below.
ClassDiagram Diagram

Class	Description
ClassDiagram	This contains the graph and graph drawing for the class diagrams.
ClassGraph	This stores all of the classes that will be displayed on a diagram. It provides functions for adding related classes or nodes to the graph. The graph contains all of the nodes and edges, and does
ClassGenes	This contains the storage for the genetic algorithm used to position the classes on diagrams.
ClassDrawer	This class contains functions for drawing the graph, including classes and connections/relationships.
ClassNode	This contains one class or node in the graph. It refers to a ModelType from the ModelData.
ClassConnectItem	This contains one connection between classes.
ClassNodeDrawOption	This defines options for how to draw a node.
ClassRelationDrawOptions	This defines options for how to draw a connection between nodes.

The following shows the sequence diagram for adding class nodes to the graph.

SeqAddRelatedNodes diagram

Drawing notes:

This sequence goes through all kinds of relationships and recursively adds related nodes.
Some of the C++11 classes were removed for simplicity.
Dashed lines indicate calls to const functions.
Text with square braces indicates conditionals. [cond]
An asterisk before square braces indicates a loop. *[cond]
The C++11 range based for loop conditionals are indicated with a colon. *[:cond]
The lifeline bars are wider where there are nested conditionals or loops.

The following shows the sequence diagram for drawing the class nodes.
Draw Class Diagram Sequence

Drawing notes:

First all nodes/classes are drawn using ClassDrawer::drawNode.
All nodes are iterated to see if there is a connection between any two nodes on the diagram, then the connections are drawn using ClassDrawer::drawConnection.

Sequence Diagrams

The OperationDiagramView related classes provide the GUI for the sequence or operation diagrams, and are shown below.

The SequenceDiagram related classes are used to display sequence diagrams.

Drawing Diagrams

The drawing classes are shown below.

Class	Description
DiagramDrawer	This defines an interface with virtual drawing functions.
SvgDrawer	This draws vector diagrams for saving to SVG files.
NullDrawer	This doesn't draw anything, but is passed to functions to allow calculating sizes of objects.
CairoDrawer	This draws diagrams to a Cairo object for drawing on the screen in GTK.

Journal

The Journal related classes are used to keep a volatile history of modified diagrams, and are shown below.

Class	Description
Journal	This keeps a collection of journal records.
JournalRecord	This is a virtual base class that allows the journal to keep different types of records. The viewable display can be different for each record. When each record is selected from the journal, the display is updated.
JournalListener	This allows the journal to update a client when a class or operation is selected to be displayed.
JournalRecordClassDiagram	This contains data for displaying one class diagram, and responding to class events.
JournalRecordOperationDiagram	This contains data for displaying one operation diagram, and responding to operation events.
OperationDiagramListener	This allows the operation diagram to notify the journal record when a new class should be displayed.
Other	The other classes are described elsewhere.

Diagram Notes:
The JournalRecordClassDiagram owns the lifetime of the ClassDiagram as shown by the filled aggregation diamond, which means that every record can contain a different class diagram.

OovEdit

The OovEdit component is a simple C++ code editor. It uses CLang to hightlight keywords.

OovEdit Main Classes

The class relations are shown below.

Class	Description
Editor	This is the high level class that provids all editing features.
DebuggerListener	This allows getting updates about the debugger
Debugger	This is an interface to a debugger
EditFiles	Keeps editor information about a text/source file.
FindFiles	Provides find text in files

EditFiles

The editor edits files selected using tabs. Each file has a buffer of text that is highlighted in C++ mode. An indenter handles keys for indenting.

Class	Description
EditFiles	Keeps information about all files. There is typically one file that has the focus.
FileEditView	Keeps information about a single file.
HistoryItem	This is for undo and redo. Each item keeps the information for one operation.
TokenRange	This is a set of tokens within a range of line numbers.
Tokenizer	The tokenizer parses a C++ file, or the contents in memory and finds a set of tokens.
Highlighter	The highlighter gets a set of C++ tokens, and defines tags to apply to the text view. The tags are color attributes to apply to the text.
Indenter	This class handles indenting of lines using the tab and backspace keys. It also handles indent using tab and untab of selected regions.

Edit Highlight

The editor uses CLang to highlight C++ code.

Class	Description
Highlighter	This uses the tokens to apply tags to the GTK visible drawing area. Different token types will be drawn in different colors.
HighlighterBackgroundThreadData	This contains all data used by the background thread. It also contains the shared data between foreground and background.
HighlightTaskItem	The highlighter/tokenizer is used to highlight, find tokens, and show members. These items indicate which background job to perform.
Tokenizer	This uses CLang to save tokens. Tokens are types of C++ text such as punctuation, comments, keywords, etc.

Debugger

The editor contains a debugger. The debugger handles typical operations such as single stepping, setting breakpoints, displaying results, and starting and stopping the program being debugged.

Class	Description
Debugger	Provides the top level interface for the debugger
DebuggerLocation	Defines a line number in a file
DebuggerBreakpoint	Defines a breakpoint location
DebugResult	Used for parsing results from the debugger.

OovCMaker

This is a command line tool that creates CMake files from a project. The synopsis is:

OovCMaker project_directory [-v][-w][-nProjName]

Switch	Description
-v	Verbose
-w	Write output to project directories
-n	Specify the project name. For example: -nOovaide

Libraries

The following are the libraries created in the OovAide project.

Library	Description
OovCommon	The OovCommon library contains shared code used by each of the components.
OovGuiCommon	The GUI library defines interfaces to GTK.

OovCommon

The OovCommon library provides code that can be used by all components.

Model Data

The class relations for the Model Object classes are shown below.

Class	Description
ModelData	This contains information about all parsed information.
ModelObject	This is the base type for all objects saved in the ModelData.
ModelType	This is the base type for classes or simple types such as "int", etc.
ModelClassifier	This contains information for each class or struct from the C++ file.
ModelAssociation	This defines inheritance relationships.
ModelModule	This keeps track of the source file of a definition.

The following shows the classes related to the ModelClassifer.

Class	Description
ModelClassifier	This contains information for each class or struct from the C++ file.
ModelAttribute	This is a data member of a class or struct.
ModelOperation	This contains information about a function prototype or definition. This is used for inline or out-of-line definitions.
ModelStatement	A statement defines a open or closed nesting, a method call, or usage of a class variable.
ModelDeclarator	Defines a type reference with a name. The type reference is const since the type must already be defined in the ModelData.
ModelTypeRef	Defines how a type is referenced.
ModelBodyVarDecl	This is used for variables defined in function.
ModelAttribute	This is member type definition as part of a class or struct.

Reading Model Data

When the types are read from the XML files, not all information about each class is in every XML file. This means that some XML files contain just a reference, and if the XML file does contain the information, the reference is upgraded from a simple type, to a class type with attributes and operations. This means that any other object that has references to the replaced type will need to point to the new object. The ModelData::replaceType function does this operation.

Replace Type sequence

Drawing Notes:

Attributes, operations, body variable and inheritance relations are all checked for references to the existing type
The *[: classifier] indicates the C++11 range-based for loop.
The [attr->getDeclType() == existingType] is the condition that is checked to see if the existing type is referred to by any attributes.

Packages

Packages are definitions of include and library paths that are external to the project.

Class Name	Description
AvailablePackages	Lists available packages on the machine. Stored in bin/oovaide-allpkgs-win.txt for windows, pkg-config for Linux. The Root directory may have wildcards in Windows, and are resolved in the package dialogs in the oovaide program. On Linux, the pkg-config program already contains full path, include, and library file paths and names.
ProjectPackages	Packages used by the project. Stored in oovaide-pkg.txt in the project directory. This file is the same format as the AvailablePackages, except that the Root directory wildcards have been previously resolved, and only the packages specified in the project are present.
BuildPackages	Stored in oovaide-tmp-buildpkg.txt in the project directory. Oovbuilder creates these files, and adds all paths that contain include and library files that are found from the search paths.
AddPackageDialog	List all available packages, and allows selecting one to add to the project.
ProjectPackagesDialog	Lists all project packages, and allows adding or removing packages, and allows editing paths and args for each package.

Child Processes

Child processes are used by the OovBuilder to run the OovCppParser, compiler, and linker, etc. They are also used by oovaide to run the OovBuilder, and the editor.

File	Description
OovPipeProcess	This starts a child process with a stdout, stderr, and stdin pipes. The listener is called when information is received from a pipe.
OovPipeProcessWindows	There is a separate implementation for Windows and Linux.
OovBackgroundPipeProcess	This creates a pipe process, and creates a thread to listen to the pipes.
oovProcessListener	Provides a simple listener where the callbacks are virtual.
oovProcessStdListener	This listener writes the stdout and stderr information to files.
oovProcessBufferedStdListener	This listener collects the std output from the child process and periodically outputs to stdout and stderr. Since all output is not sent out at the same time, the process ID string is prepended each time there is some output in order to handle output from multiple child processes.

OovGuiCommon

The OovGuiCommon library provides code that can be used by all user interface components.

Build Processing

For detailed information on processing, see Oovaide Build Design. The analysis mode described below is often run as part of the build mode.

Analysis Mode

The oovaide program invokes the OovBuilder to extract drawing information. OovBuilder runs the OovCppParser for each file found as it recursively navigates the source directory tree. These modified data flow diagrams were made using Inkscape.

File	Description
oovaide.txt	This contains the source root directory, the compiler and link arguments, and the tool names.
oovaide-buildconfig.txt	Contains information about recently built configurations
oovaide-comptypes.txt	Defines the component types, such as static library, etc.
analysis-<crc>/oovaide-comps.txt	This file contains scanned information about the internal and external components.
analysis-<crc>/oovaide-incdeps.txt	This file contains the C++ header include dependencies, and the update time of each file
analysis-<crc>/*.xmi	This is the extracted output of each cpp and h file that is used for analysis drawings.

Build Mode

When a build is performed, the component types are used to determine what type of component to build.

File	Description
\bld-\.o	The object modules as a result of compilation
\bld-\sym\.txt	The library symbol information
\bld-\.a	The library produced for static library components
\bld-\.exe	The executable produced for program components

Multitasking

See the document MultiTasking