IncludeManager Tutorial

This tutorial will walk you through the process of creating #include dependency graphs of your files and projects. It is designed to be quick and simple so you can get up and running quickly. For more in-depth information on IncludeManager's facilities, see the reference section.

First steps

First, ensure you have a C++ project loaded into Visual Studio. In this example we will use an empty default MFC application created with the AppWizard called 'TestApp', but it's just as easy to use an existing project.

We'll start by viewing the #include dependencies of a single file. To do so, open the file you're interested in, in this case we choose the main class file 'TestApp.cpp'. Once loaded, click the 'Show Include Graph' button on IncludeManager's toolbar:

The IncludeManager Toolbar

A new window will pop up immediately, and will show an animating progress indicator while the file is being analysed. In a few seconds the full include graph of the file will be displayed:

The include graph for 'TestApp.cpp'

Finding more information

You'll notice the various files are represented by square and diamond-shaped coloured boxes. Square boxes represent source files and user header files. Diamond-shaped boxes repesent system includes. By hovering your mouse pointer over the files you can see a tooltip displaying the full path to the file, and by clicking on the file you open that file in Visual Studio. By hovering your mouse pointer over the lines connected two files you can see the position in the file where one includes the other, and by clicking on the line the Visual Studio editor will highlight the line of the #include which connects the two files:

Here the line between 'TestApp.cpp' and 'TestAppDoc.cpp' has been clicked and the relevant #include has been highlighted in the editor

The include graph window is fully dockable: Note how we have docked the include graph window to the right of the code window. IncludeManager continuously monitors the editor and by modifying the source text you will notice the graph updates in real-time. To demonstrate this, comment out one of your #includes and note the graph updates once you've moved your cursor off the affected line:

The include for 'TestAppDoc.h' has been commented-out and the graph has automatically updated

While the graph is updating you can continue working as normal, IncludeManager will process changes in the background. This allows you to experiment with various #include strategies and see in real time how that affects the include graph of your files.

Expanding and contracting

As you've moved your mouse pointer over the files you may have noticed the +/- icon at the right-hand extent of the file. This is the collapse icon and allows you to collapse and expand files. A collapsed file is displayed with a dotted outline and a greyed-out arrow leading out - its includes are not displayed. This allows the graph to be kept to a manageable size by pruning down the areas you're not interested in. In this example we collapse the 'StdAfx.h' file to reduce the size of the graph:

Note the collapse/expand icon on the right of the file when you mouse over

Viewing a collapsed 'StdAfx.h'

By default all the system includes are collapsed. However if you want to follow the include path through the system files you can either expand the relevant files in turn or turn this behaviour off in the Options window. To open the Options window click the options icon on the toolbar:

Options button

This will open the Options window. Note if you have a smaller graph window the options button may have spilled off the end of the toolbar. In this instance you can access it via the drop-down at the right edge of the toolbar. On the Options window, de-select 'Stop at system includes' and click OK:

The Options window

The graph will redraw with all the system includes expanded - which in the case of MFC libraries makes the graph rather more complex:

With 'Stop at system includes' disabled you can see the full include graph

In most cases it's best to leave the 'Stop at system includes' option enabled.

Finding your way around the graph

It's often necessary to zoom in and pan around the graph to investigate it fully. By dragging on the background of the window you can pan the graph, and the mouse wheel will zoom in and out. If you don't have a mouse wheel, or prefer to drag to zoom, you can choose between moving and zooming using the relevant icons on the toolbar, where you can also zoom in and out by increments and scale to fit. Additionally an edit box on the toolbar allows you to your own zoom level.

The toolbar's move and zoom controls

With larger graphs it may become difficult to find the exact file you require. In this situation you can use the search functionality. Simply type in the Find box on the toolbar and any matching files will be highlighted as you type. Pressing enter or clicking the 'Find' icon then zooms the graph to the first matched file. Subsequent presses then move to each of the remaining matches in turn.

Interactively seaching for 'Test'...

...now searching for 'TestAppDoc'

After clicking 'Find' the view zooms on the match, and highlights the #include path

Viewing a project graph

IncludeManager also supports looking at a whole project's interdependencies. To view a project in the graph window first select the relevant project in Visual Studio's Solution Explorer, then click the 'Project Include Graph' button:

The 'Project Include Graph' button

As before there will be a short pause while the project's dependencies are calculated, and then the full graph will be displayed:

A full project graph

A very useful question to be able to answer is 'If I modify this file, which other files will rebuild?' With IncludeManager, answering this question is easy. By right-clicking on a file and selecting 'Show include paths' you can highlight all the possible ways that file is included:

'Show include paths' applied to 'resource.h'

This feature is useful when reducing dependencies on header files. By picking a commonly-included header file and showing the include paths you can find extraneous inclusions of the file - any file that highlights in red and that doesn't use functionality defined in the header is a candidate for refactoring.

Getting more information

This tutorial should get you up and running with IncludeManager. For more information see the Reference section, visit the IncludeManager Forum on the ProFactor website, or contact support@profactor.co.uk for more help.