Including Headers in SciTools Understand

It took me a long time to best set up my includes in Understand. While most of us won’t spend much time fine tuning Understand and will rely on Understand’s default configuration, this article explains how to get maximum accuracy in your project by accurately setting the headers.

Introduction

Should you read this paper? Yes, if you are using Understand to analyze C and C++.

How should I read this paper? Try the examples. They are simple and it should take no more than 15 minutes to go through all of them.

What will be my benefit? You will become an expert for C/C++ project and it will help you get better results from the tool.

Where do you set the headers/includes in Understand?

The header options are set in 2 places. Both are in the project configuration window, that you access through the menu Project >> Configure Project 

Project >> Configure Project

In your project files

“Project Files” Window

In your Include directory options

“Include Options” Window

IMPORTANT: Later in this article, I will refer to those 2 places as the “Project Files” and as the “Include Options”.

WARNING: The Include Options are saved with the .UDB file, so each UDB file will save its own configuration after they are set. But the last options you used will become the default options for any new project. So before you start working the examples, make sure to note the options you have been using until now. You can fall back on them later if needed.

A Simple Example

Let’s create a directory that contains

  • function.h file (header) in an include directory,
  • a function.cpp (source) in a source directory:

Your directory structure should be something like the structure on the right.

The source code files are:

function.h

#ifndef __function__
#define __function__
int function(int a);
#endif

function.cpp

#include "function.h"
int function(int a)
{
	return 0;
}

Let’s get Started with a simple Project

Set up our 1st project

  1. Create a UDB project with the “bare minimum” settings.
  2. Create a project with C++ Strict Settings.
  3. If you use Fuzzy C++, you can follow the same instructions, but your “Include Options” will be different.
  4. Add the “Include” directory to your “Project Files”
  5. Add the “source” directory to your “Project Files”

Make sure you have nothing selected in the “Include Options”, so it will look like this:

Analyze the project, using CTRL-ALT-R or Project >> Analyze All Files.

The Results

In the Entity Filter (on the left), you will notice that function.h is greyed out, usually meaning the “entity function.h” is not defined.

This is surprising because the file “function.h” is in the project file.
Double-click on function.h and you will get the “undefined” window.

Even more surprising, if you right-click on function.h and select Graphical Views >> Included By, you will get the following graph:

This tell us SciTools Understand knows that function.cpp includes function.h, but also that SciTools Understand is not able to find function.h (surprising because the file was in the project files).

Explanation: What happened? What went wrong?

We can sum it up with 2 points:

  1. SciTools Understand analyzes all the source code files, but it does not analyze all the files in the project. If a header is not “included”, it is not analyzed.
  2. We have also not yet told SciTools Understand where to look for headers.

SciTools Understand has not analyzed the header file and this is confirmed in the analysis log. It shows that only function.cpp was analyzed:

We can force SciTools Understand to analyze all headers in the project files, even if they are not included. To do so, select the option “Analyze unincluded headers in isolation” in the “Include Options” (This is available only in the C++ Strict parser)

Select this the option and re-analyze all the files using CTRL-ALT-R or Project >> Analyze All Files.

The Entity Filter (on the left) now shows the following:

We can see that the macro “_function_”, the function “function” and the parameter “a” are now defined, indicating that function.h was analyzed.

But why do we have 2 “function.h”? One is black (defined) and one is greyed out (undefined).

Why? We have not yet told SciTools Understand where to look for headers. So it doesn’t know that the function.h it found in our project files is the one that function.cpp is looking for. In fact, do he following: Open function.cpp and right click on the #include “function.h” line. The “Edit File” will be greyed out showing that SciTools doesn’t know where to find the file.

So, Understand is showing us 2 entities “function.h”:

  • The first one, in black is the function.h file that is in our “Project Files”. We know all about this file and it was analyzed.
  • The second one, in grey, is the function.h file that is included by function.cpp, but SciTools Understand wasn’t able to locate it.

We are going to fix this next.

IMPORTANT: Before we proceed, make sure to remove the option “Analyze unincluded headers in isolation” in the “Include Options”.

Our 2nd Try: Showing Understand where to find headers

You have 2 choices to do so:

  • The automatic way: We can tell Understand to look for headers in our “Project Files”, and Understand will automatically look for the headers in them.
  • The manual way: We can setup the include directories in the “Includes Options”, just like a compiler. SciTools will look in the specified directories for headers. The include directories added can be folder in our “Project Files”.

Trying the Automatic Way

  • In the “Include Options”. Make sure to unselect “Analyze unincluded headers in isolation” and then select “Search for Include files among project files”.

  • Re-analyze all the files using CTRL-ALT-R or Project >> Analyze All Files

The entity filter now shows what we expected, where function.h appears only once and is black. SciTools Understand was able to “make the connection” between the header in our “Project Files” and the header that function.cpp was trying to include.

Trying the Manual Way

  • In the “Include Options”, make sure to unselect both “Analyze unincluded headers in isolation” and “Search for Include files among project files”.
  • Add the directory that contains the include.h in the list of includes using the “New” button.

  • Re-analyze all the files using CTRL-ALT-R or Project >> Analyze All Files
  • You get the same result than the automatic way.

So, what should I choose: Automatic or Manual?

There are two different ways to let Understand know where to find the headers file, one automatic and one manual.

We have also seen that without any setup, Understand would not know where to find the header files, even if they are in the project files.

Both will work the same in most cases, but some problems may arise when you have multiple headers with the same name in your project (a common example is config.h). In this case, the automatic method will silently and arbitrarily pick one (as there is no way for Understand to know which one to pick) and this may lead to confusion on large project.

So my suggestion is to always set up your header manually unless the project is fairly small and you are running a quick analysis being ready to assume the “risks” of duplicate headers.

You will notice that some “Include Options” let you select “Ignore directories in header name”: This helps with includes that are like #include “rw/cstring.h” for example. This is not covered here.
For some of the “Include Options”, you will see a distinction between “system include” vs. “include”. For Understand, a system include is anything included using < and > (Ex: #include ) and will consider an include anything included using “ (Ex: #include “header.h”). Again, we won’t cover it here but contact us if you need help.

What to do with 'External' or 'Library' headers?

So far, we have assumed that the include files are in your project files.

But when dealing with 3rd party libraries or system include, we may not want all their files added to our project. Let’s see how to deal with those by implementing a small example where we will include library.h, a header file that is not part of our project but is coming from an external library.

Modifying our test case

Let’s add a library.h into our directory structure in a directory folder.

Here is the code for library.h

#ifndef __library__
#define __ library __
int library(int a);
#endif

Let’s also modify function.cpp to include “library.h” and use the library() function.

#include "function.h"
#include "library.h"
int function(int a)
{
library(a);
return 0;
}

IMPORTANT: DO NOT ADD THE library.h or the library folder in your Understand project. Also, make sure the library.h is not picked up automatically by the project as it may be in a “watch directory”.
To be sure, do the following:

  1. Create library.h in a directory not picked up by your project
  2. Modify function.cpp
  3. Hit Project >> Rescan Directories
  4. Go in your “File Options” and make sure it’s not there. Your “File Options” should not contain the library.h
  5. If it is picked up, just locate library.h in a directory that isn’t picked up

Let’s re-analyse the project!

Because, in most cases, we don’t want to add the 3rd party libraries to our Project Files, we can only use the manual method.

So, let’s first analyze all the files after we have modified the function.cpp. Let’s do it without changing anything to the project, by using CTRL-ALT-R or Project >> Analyze All Files

As expected, we will see a grey library.h in the entity filter.

This not much different from before, and the expected result. SciTools understand doesn’t know where to find library.h. If you double click on library.h, it will show you the following window:

The analysis also shows a single error for the missing include:

Let’s add library.h in the “Include Options”

Let’s add the library folder (the folder that contains library.h) in the “Include Options”, similarly to what we did earlier.

Add the directory that contains library.h to the Includes in the “Include Options”

Analyze the whole project by using CTRL-ALT-R or Project >> Analyze All Files

Notice that the error has disappeared. You have a complete analysis with 0 error.

The entity filter now shows the following:

You will immediately notice that library.h is still grey, which may at first seem incorrect because SciTools Understand should be able to find it. Don’t worry, it’s not!

Double-click on “library.”, and instead of getting the “undefined windows”, it will open the right file! Note that the source will appear with limited syntax highlights.

What happened?

While it may seem confusing at first, this means that SciTools was able to find the header, has analyzed it, but didn’t not “add” the resulting information to the project. It simply used what it needed. This is how you want to set up a 3rd party library in your project.

In this case, the analysis is successful because it finds all the headers it needs, but the analysis doesn’t “bring them” in your project.

Here is a good example: If you count the total number of source code lines in the project, would you want to count the line library.h? Probably not… this is why the library.h isn’t “defined” in your project.

It also means that having some grey entities and headers in your project is perfectly fine. It also shows you not having all headers in the “Project Files” is a valid strategy for 3rd party libraries.

Optional: Adding “3rd party headers” to the “Project Files

This is all there is about 3rd party library, but I am going to show you one last options. We are going to see how we can automatically add the headers in the “Project Files” if we wanted to do so. But be careful with this one! With some recursive effect, you may end up analyzing all the headers on your system. A good example of what not to do is analyzing the STL…
I use this technique only when I want to add all the dependencies of my project in my project.

Here is how to proceed:

Add the “Add found include files to source list”

Analyze the whole project by using CTRL-ALT-R or Project >> Analyze All Files

The entity filter now shows library.h in black. It has been added to our project files, so it is now “fully defined”. If you were to count the number of lines in the project, the lines in library.h would now be counted.

“library”, the function, remains grey. This is normal because we don’t have an definition for it, only a declaration.

Observe that if you go back to your “Project Files”, you will see that library.h has been added to your project.


This is not reversible: This means that once you have added the files this way, you will have to remove them manually even if you unselect “Add found include files to source list”. This has ruined some of my projects, so be careful!

Conclusion and Recommendations

The goal of the paper was to help you understand the basics on how SciTools Understand is going to deal with include files. You should experiment until you get a good sense for what you do.
To finish, I will show you how I get started with understand projects.

Here are two of my best practices, but, please, try your own alternative ways until you find what works best for you.
Here is what I do:

OPTION A: If I don’t know anything about the project, and want to have a quick look at it:

  • Include the .cpp and the .h that are part of your project in your “Project Files”, but be somewhat careful to not add duplicate headers with a quick manual review.
  • Do not include 3rd party libraries code in your project files (no header, no cpp)
  • Do not include test/validation source code in your project files.
  • In a C++ Strict Environment, select those options:

In Strict C++

  • In a C++ Fuzzy Environment, select those options:

In Fuzzy C++

  • Add the 3rd party library include directories into the “Include Options”.
  • Do not set any include for your project. We’ll let understand find them.
  • Run the analysis

OPTION B: If this is my project and I want to set an analysis with minimum error:

  • Include the .cpp and the .h that are part of your project in your “Project Files”, but be somewhat careful to not add duplicate headers with a quick manual review.
  • Do not include 3rd party libraries code in your project files (no header, no cpp)
  • Do not include test/validation source code in your project files.
  • Both in C++ Fuzzy and C++ Strict Environment, do not select any of the options in the “Include Options”. Your window should look the following where no option is selected:

In Strict C++


In Fuzzy C++

  • Add all your project’s include directories manually into the “Include Options”
  • Add the 3rd party library include directories into the “Include Options”
  • Run the Analysis

Of course, do not forget to set up your macros correctly as well as some of the language options (in case of C++11 and C++14 for example). If you liked this paper, we are offering full trainings on all of the SciTools Understand features. Please Read the next steps and email us your questions/comments. Thanks a lot for reading.

Next Steps

Best Learning!
  • Onsite Training
    • $ 3,000 5 students
      • The Author at your site
      • Full Day of learning
      • Optional Extra Student
Easy Option
  • Remote Training
    • $ ASK per session
      • 5 Hrs online session
      • Follow-Up Q&A
      • Easy To Setup
      • Just pick the day and reserve yours soon!
FREE OPTION!
  • Free Webinar

Contact the Author and Emenda USA

Your Email:
Your Phone Number:
Your Message:

Quality - Security - Compliance