When a new project is created the following can be defined.
Oovaide scans the directories of the project under the source root directory (excluding exluded directories) to find source files that need to be analyzed. The extensions of the files in the directories are used to determine which source file parser to use. Oovaide can analyze and build a single directory tree that contains both C++ and Java files. In fact, Oovaide itself can be built this way.
Oovaide scans all non-excluded directories in the project, and adds include directory paths to the compiler command line for any directories in the project that contain header files. If there are files with duplicate names, it is possible to add a -I switch to include the needed directory first and it will be used before the project include paths. It is possible to do this component or directory specific by using the build settings dialog, or editing the oovaide.txt file itself.
OovAide uses the CLang parser for analysis. This means that problems with include paths can be solved by searching the web for typical CLang installation problems
Oovaide by default uses one set of compiler settings for all directories. This means that a superset of all packages should normally be specified in the common build arguments. For example, if gtk is not needed for some directories, adding it for all directories should not cause a problem for directories that do not require gtk. It may make analysis slower, but should not fail. This can be changed for complex projects.
Each header and source file is analyzed independently. This means that each file should be able to include all definitions needed. Search the web for "self-sufficient headers", or "self-contained headers", for more information. On many projects, a fairly small include change can be made to the source to be able to analyze much of the source.
Not all compiler errors need to be fixed to generate useful diagrams. Oovaide will still generate references to undefined objects as long as the compiler has parsed beyond the initial errors. If the files do not include all needed definitions (they expect the source that includes them to include other files first), then the error limit may need to be increased so that more of the file can be parsed. The other alternative is to fix the header files so that they include the needed definitions.
In Linux, the CLang compiler is not shipped with Oovaide, but must be present on the system.
Packages are different on Windows and Linux. On Linux, the pkg-config tool is used by the Oovaide package dialogs so that packages can be selected and used in each project.
On Windows, there is a file called bin/oovaide-allpkgs-win.txt, that defines a few common packages. This file can be easily read to see how packages are defined, and it is possible to modify and add more packages. You can always file a bug to get another package added.
On Windows, Oovaide attempts to find directories using wildcards in the package directory definitions. If there are multiple versions, then the directory can be specified manually.
If the "Include Directory" setting is a wildcard, then the directories are scanned for include files, and paths are saved. To prevent this scan, directories can be specified (separated with semicolons) or a single period can be used to specify that only the current directory relative to the root should be used as the path.
The argument order is important if there are files with the same names in different directories.
| Flag | Name | Description |
|---|---|---|
| -EP | External Packages | This flag should be added using the "External Project Packages" button. This specifies the name of the package to use for the OovBuilder. |
| -ER | External Recursive Directories | This flag allows specifying a root directory to search for includes and libraries. It also allows specifying exclude directories. An example is "/rootdir/!/test/!/examples/", so that any filepath that matches test or examples will be excluded. |
| -lnk | Link Flag | The value following this flag is sent to the linker. Some examples are "-lnk-L/libdir", or "-lnk../dir/objfile.o". |
See the Inkscape Example below for more problem solving information.
On Linux, the library is not supplied. If the library does not exist, an error like the following will occur. "error while loading shared libraries: libclang-3.6.so.1: cannot open shared object file". A package manager will allow adding the CLang package that is required. In Debian systems such as Ubuntu, the Synaptic Package Manager can be used to find the package by searching for "clang interface", and it may be named something like libclang1-3.6.
If an error appears such as "error: 'stdio.h' file not found" or for 'limits.h' or 'stddef.h', this means that CLang is not finding the include files in some standard locations. It is possible to find the locations that CLang is looking by using the -v switch in the Analysis/Settings menu on the C++ Settings tab in the Common Build Arguments edit box. On Debian, the package that includes the files is libclang-common-x.x-dev, which is included by using libclang-x.x-dev. Sometimes using the build-essentials may help.
It is possible to find the intersection of files that packages supply,
and where clang is searching using the following. Using "echo '#include
The Analysis/Settings menu selection will display a tab named "Java Settings". This tab allows setting the class path and JDK path.
The class path is initialized from the CLASSPATH environment variable, but altering it in the settings will not change the CLASSPATH environment variable. The class path must contain all jars that are needed for your project. The CLASSPATH environment variable does not need to include tools.jar since it is added from the JDK path as described below.
The JDK path is initialized from the JAVA_HOME environment variable, but altering it in the settings will not change the JAVA_HOME environment variable. In Linux, if JAVA_HOME is missing, then "/usr/lib/jvm/default-java" is used as default. The JDK path must be set to the JAVA SDK. An example is: "C:\Program Files\Java\jdk1.8.0_51". This path is used to find the tools.jar file in the lib directory.
The Extra Analyze Arguments can be used to set switches, or to add java files that will be added to the analysis.
The Build Settings dialog under the Build menu allows selecting a
directory and specifying what type of component to build from the
directory. For example, if a single executable will be built from the
whole directory tree, then select the
The following directory structure shows how components can be created. See the user guide for more information.
Some of the rules are:
The classpath must include all jars that are required for the build. The Java Library Jar can be used to build a jar that is not a stand-alone executable. At the moment, Oovaide does not determine jar dependency build order, so if this is a problem, multiple projects may have to be created to work around this for now.
The package names must match the directory structure. For each jar that is created, the package names in the java files must match the directories under the specified component's directory.
The Extra Build Arguments can be used to specify switches or to add jar, java or class files.
On the Analysis Settings dialog, there is an Advanced button that allows setting build variables. All of the settings used for the build are defined using build variables, so the Advanced button allows changing the build variables with much more flexibility than the other screens.
Build Variables are used to define compiler and linker flags, tool paths, and other environment variables. Each variable can have some settings, and in some circumstances will be modified to append more settings. For example, the base setting of the project for C++ arguments may include some directory using a "-I/path" flag. Then for a particular component/directory, an additional "-I/otherPath" may be appended to the base settings of the project. Another example is that an external package may be different on Linux or Windows.
The build settings that are used are only the settings where the filter matches the current build being performed. For example, a C++ build variable with no filter will match all C++ files. A variable with a filter where the configuration is Debug, will only be used when the compile being performed is for debug mode.
The build settings are run in a particular order. In many cases the order may not matter, but an example of where they may matter is when there are duplicate header files, and one must be searched first. The shortest rules are run before longer rules.
For this example, we will attempt to analyze the Inkscape program. The Inkscape program requires gtkmm and boost, so they need to be added as external packages. Since gtkmm includes mingw, there is no reason to additionally add a separate mingw package.
I don't know which version of gtkmm is needed, so I just downloaded the Tarnyko gtkmm-3.4.0_mingw-4.6.2 version. Use Oovaide to add gtkmm as an external package.
At first, there was a compile error about a missing config.h. I never ran the configure command, so I cheated and copied config.h.in to config.h in the Inkscape source code.
The following problem is displayed during analysis, and resolved by adding an include of "gtkmm-3.0/gtkmm.h" to the Inkscape source in src/extension/param/parameter.h. The real problem is that Inkscape does not define all classes before they are referenced in header files.
C:/Dave/Mine/software/external-projects/inkscape-0.91/inkscape-0.91/src/ extension/param/parameter.h:42:8: error: use of undeclared identifier 'Glib'Similar to the first problem, more includes need to be added, so add the following includes to the parameter.h file before the gtkmm include. #include "xml/node.h", #include "extension/extension.h".
C:/Dave/Mine/software/external-projects/inkscape-0.91/inkscape-0.91/src/ extension/param\string.h:17:28: error: expected class name C:/Dave/Mine/software/external-projects/inkscape-0.91/inkscape-0.91/src/ extension/param\string.h:27:86: error: use of undeclared identifier 'Parameter'Inkscape defines float.h which conflicts with the external mingw library float.h. This problem can be eliminated by selecting "Analysis/Project Settings", and adding "inkscape-0.91/src/extension/param/" to Exclude Sub-Directories.
C:/Dave/Mine/software/external-projects/inkscape-0.91/inkscape-0.91/src/ extension/param\float.h:32:23: error: unknown type name 'gchar'The CLang compiler requires intrinsics from its own header file, and cannot use the one from mingw. The CLang compiler searches some paths which can be seen by adding the -v switch to the compiler options. The first files that CLang is searching for are shipped in the CLang package under the LLVM/lib directory. These must be found before the mingw directories. The best option is NOT to add the mingw directories to a project, since CLang will normally find them. Another option may be to use "-Iclang/3.6.0/include" before the other external package ref arguments ("-EP").
/gtkmm340_mingw462/lib/gcc/mingw32/4.6.2/include\ia32intrin.h:41:10: error: use of undeclared identifier '__builtin_ia32_bsrsi'Inscape requires the Boehm garbage collector. This can be added by defining a new external package, or by using -I with the "include" directory specified. The sigc++ library can be added in the same manner with the "sigc++" directory specified. These packages are probably not needed to get a pretty good analysis of Inkscape.
C:/Dave/Mine/software/external-projects/inkscape-0.91/inkscape-0.91/src/ gc-core.h:25:11: fatal error: 'gc.h' file not foundTo summarize, by modifying two source files, and creating a simple Oovaide project, it was fairly easy to perform analysis on the Inkscape project.