绘制函数调用图（call graph）（4）：doxygen + graphviz

专栏导读

本专栏第一篇文章「专栏开篇」列出了专栏的完整目录，按目录顺序阅读，有助于你的理解。

前言

doxygen 也可以生成函数调用关系图，但 doxygen 能做的远不止于此，它是一款优秀的文档自动生成工具。它可以将代码中的注释转换成帮助文档（注释格式要符合 doxygen 要求才行，FFmpeg API Documentation 就是用doxygen自动生成的），它也可以通过静态分析代码，生成「头文件引用关系图」、「函数调用关系图」、「继承图」以及「协作图」来可视化文档之间的关系。

官网：http://www.doxygen.nl/

根据官网介绍，截止书稿，它能支持的语言有：C, C++, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL等。生成的帮助文档格式可以是CHM、RTF、PostScript、PDF、HTML和Unixman page等。

有了这样的工具，在发布程序版本的同时，发布帮助文档也将变得简单、高效，配合持续集成系统（如Jenkins），自动构建系统，帮助文档可以跟随代码一起实时、轻松的发布版本。

doxygen 是跨平台的工具，支持Linux、Windows、Mac OS X系统，本文将以Windows版本为例，简要介绍如何使用 doxygen 生成函数调用关系图，其他功能（如将代码的注释生成帮助文档）不在本文讨论范围内，这是一个入门级的教程。

安装graphviz

跟前面文章介绍的cflow、codeviz一样，doxygen 自身没办法生成关系图，需要依赖 graphviz 才行，所以还得安装 graphviz 先。

官网：http://www.graphviz.org/
下载：https://graphviz.gitlab.io/_pages/Download/windows/graphviz-2.38.msi

在官网上很容易找到 Windows 平台的 Stable 最新版本，如下图所示，我下载的版本是「graphviz-2.38.msi」，安装过程一直“Next”即可。

图 2-1 选择Stable版本下载graphviz

安装doxygen

官网：http://www.doxygen.nl/
下载：ftp://ftp.stack.nl/pub/users/dimitri/doxygen-1.8.14-setup.exe

在官网上很容易找到最新版本的安装文件，我下载的版本是「doxygen-1.8.14-setup.exe」，安装过程也是傻瓜式的“Next”。

开始之前

截取 doxygen 安装目录树（只是部分），如下所示：

doxygen
├── bin
│   ├── doxygen.exe            <-- 最核心的可执行文件
│   └── doxywizard.exe         <-- 配置文件向导
└── doxygen_manual.chm         <-- 离线帮助手册

其中 doxygen_manual.chm 是离线帮助手册（要深入研究 doxygen 的，认真研读这个手册就对了）， doxywizard.exe 是配置文件向导，通过这个向导可以快捷地生成配置文件，doxygen.exe 再根据配置文件分析源码，输出各种图和文档。以下这张图更能直观的表达出 doxywizard.exe 和 doxygen.exe 之间的关系：

图 4-1 doxygen工作原理图

下文将以分析 E:\whoami\whoami.c 源码为例，演示如何使用 doxygen，源文件 whoami.c 内容如下：

/* whoami.c - a simple implementation of whoami utility */
#include 
#include 
#include 
#include 

int who_am_i(void)
{
    struct passwd *pw;
    char *user = NULL;

    pw = getpwuid (geteuid ());
    if (pw)
        user = pw->pw_name;
    else if ((user = getenv ("USER")) == NULL)
    {
        fprintf (stderr, "I don't know!\n");
        return 1;
    }
    printf ("%s\n", user);
    return 0;
}

int main(int argc, char **argv)
{
    if (argc > 1)
    {
        fprintf (stderr, "usage: whoami\n");
        return 1;
    }
    return who_am_i ();
}

创建doxygen配置文件

Doxywizard是配置和运行doxygen的GUI前端，启动 doxywizard.exe 向导可以快捷的创建配置文件。

Step1：运行 doxywizard.exe，点击 Wizard 选项卡，配置 Wizard > Project 页面，如下图所示：

图 5-1 doxywizard 向导步骤1

注意：在使用 doxywizard 的过程发现一个bug，但凡是设置路径的（如待分析的源码路径），都要通过Select按钮启动文本对话框去选择路径，直接拷贝路径到编辑框是不生效的。可以通过 File > Save 保存配置文件去查看，或者直接在 Run > Show configuration 查看，待分析的源码路径的关键词是INPUT。

Step2：点击 Expert 选项卡，配置 Expert > Project 页面：

图 5-2 doxywizard 向导步骤2

Step3：配置 Expert > Build页面：


图 5-3 doxywizard 向导步骤3

Step4：配置 Expert > Dot页面：


图 5-4 doxywizard 向导步骤4

至此，配置完毕，可以通过 File > Save 菜单将上面所有配置导出（保存）到配置文件，以免丢失配置，配置文件默认保存在 Step1 设置的工作目录下。当然你也可以通过 File > Open 菜单导入（打开）一个现有的配置文件。可以打开配置文件看看，里面参数非常多，doxywizard 图形化的便捷性也就体现在这里，没了这个向导，就要人为手工编辑这个配置文件，可想而知那是多么的痛苦。

开始分析源码

上一章节已经配置好了参数，接下来就可以开始分析源码了。切换到 doxywizard.exe 向导的 Run 选项卡，点击 Run doxygen 按钮，幕后就会根据刚才的配置执行 doxygen.exe 命令：

图 6-1 开始分析源码

等分析完毕，最后点击 Show HTML output 按钮就会启动浏览器显示分析结果，如下图所示：


图 6-2 查看doxygen分析后的结果

选择 文件 > 文件列表 > whoami.c 页面，就可以看到「头文件包含关系图」和「函数调用关系图」：


图 6-3 头文件包含关系图

图 6-4 函数调用关系图

从图中可以发现，同样的示例代码，cflow 分析的函数条用关系图会显示系统API（如printf），而doxygen则不会显示系统API（这更符合我们的需求）。由于我的示例源码很简单，所以函数调用关系图看起来也很「简陋」。为了体现doxygen的强大性，我特意选了一个相对复杂点的源码（ffmpeg， 下载地址）来分析：


图 6-5 doxygen分析复杂点的函数关系图

总结

比起doxygen，之前两篇文章所体验的cflow、codeviz简直弱爆了，doxygen安装过程简单，使用便捷，容易上手，用户体验较好。