Introduction

When writing multi-file C application, or inheriting a project others have worked on, it is always helpful to understand how the code is structured from a file level. Ideally, you want to try to keep module dependencies running in a single direction, limiting reverse dependencies. Keeping the code structure in check can help tremendously in reducing bugs and improving code maintainability.

Embed from Getty Images

Although there are some brilliant tools for helping you to analyze the structure of your code in great detail, looking at it from different perspectives and making it easier to modify, I will be focusing on a very simple and free one that is highly effective and ideal for those who like to experiment, don’t have huge budgets, or simply don’t have a really big project to maintain.

Overview

It is called scan-depends.pl, a tiny, and obscure tool included as part of the smbase library.

  • Notes:
    • the links above don’t include the full downloadable source code.
    • I eventually found the full source code on GitHub,
      • I modified this slightly to make it more forgiving when parsing #include statements,
      • I also modified the output slightly – more to my liking.
      • My modified code can be found over here.
    • It is designed to work with the assumption that header files are named according to their C counterparts as per normal C programming convention.
      • e.g. foo.h corresponds with foo.c

As its name implies, Scan-depends.pl is actually a Perl script and it analyzes your code structure and outputs it in a format that can be parsed by the very useful and powerful open source Graphviz dot tool. As you can see below, it makes it really easy to follow the structure of the code you are analyzing. It runs well under both Linux and Windows, and would also run under other operating systems that support Perl and Graphviz.

Launching

Embed from Getty Images

If using Windows, one will obviously need to install a distribution of Perl if not already done. If unsure, I would recommend Strawberry Perl. When running with the correct parameters, it outputs a PDF file giving a really nice clear graphical picture of your project. For interest, I ran it against an open source Linux project (MSYS2-pacman) I happened to find on GitHub. Once cloned, one first needs to change to its src/pacman subdirectory.

If run from Windows (or perhaps if you haven’t set up the script to self-execute from Linux), you would prepend “perl”:

perl scan-depends.pl -I../common -I../util -r pacman.c | dot -Lg -Tpdf -ostruct.pdf

 

The following command should be used from a Linux terminal:

scan-depends.pl -I../common -I../util -r pacman.c | dot -Lg -Tpdf -ostruct.pdf

 

This produces a PDF as seen below. Note this was done from Linux. Windows does not follow Linux symlinks for this example, so would produce a slightly strange result unless the code is modified to use relative paths.

structure

Of course, there are some much more serious commercial tools which seem well suited to heavyweight code bases. They promise to make tasks such as code manipulations, transformations, and static analysis a lot easier. Some that look very interesting are:

  • Structure 101
    • I haven’t yet been able to evaluate this product.
  • Understand from scitools
    • While this more resembles an IDE and is great for showing the internals of any specific module and allowing you to make code modifications, I find that it doesn’t give as clear an overview (bigger picture) as scan-depends.pl does.
    • After a brief evaluation, I have found that many of the useful graphical features offered could also be done with a combination of tools such as Eclipse CDT and Doxygen, with a bit of extra effort.

If you know of other useful tools of this type, I would also be very interested to hear about them.

photo credit: <a href=”http://www.flickr.com/photos/113305058@N08/16378828461″>Branches</a> via <a href=”http://photopin.com”>photopin</a> <a href=”https://creativecommons.org/licenses/by-nc-nd/2.0/”>(license)</a>


4 Comments

Toby · April 11, 2016 at 11:56 am

Doxygen will do this for you if you have graphviz and have at least added ‘@file’ documentation to each header.

    Firmware Programming by Bryan Jarmain · April 11, 2016 at 12:51 pm

    Toby thanks, Doxygen is something I mentioned, and I use it regularly, and it can be very useful for displaying the call trees of individual functions, as well as to some extent showing the include trees (in a different format). There is some overlap.

Back to Basics Source Code Comprehension - Firmware programming · December 31, 2017 at 3:03 pm

[…] with certain automated tools that just focus on the file level of your code. For example, in a previous article, I demonstrated the use of a Perl script (ScanDepends) that uses Graphviz to show how C files are […]

Scan-depends, a Useful little Script to Visualize C Code Structure – Firmware Programming · July 14, 2018 at 6:05 pm

[…] This article has moved. Please visit it by clicking here. […]

Leave a Reply

Your email address will not be published. Required fields are marked *

%d bloggers like this: