專欄導讀

本專欄第一篇文章「專欄開篇」列出了專欄的完整目錄，按目錄順序閱讀，有助於你的理解。

前言

doxygen 也可以生成函式呼叫關係圖，但 doxygen 能做的遠不止於此，它是一款優秀的文件自動生成工具。它可以將程式碼中的註釋轉換成幫助文件（註釋格式要符合 doxygen 要求才行，FFmpeg API Documentation 就是用doxygen自動生成的），它也可以通過靜態分析程式碼，生成「標頭檔案引用關係圖」、「函式呼叫關係圖」、「繼承圖」以及「協作圖」來視覺化文件之間的關係。

根據官網介紹，截止書稿，它能支援的語言有：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 先。

在官網上很容易找到 Windows 平臺的 Stable 最新版本，如下圖所示，我下載的版本是「graphviz-2.38.msi」，安裝過程一直“Next”即可。

圖 2-1 選擇Stable版本下載graphviz

安裝doxygen

在官網上很容易找到最新版本的安裝檔案，我下載的版本是「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 <pwd.h>
#include <sys/types.h>
#include <stdio.h>
#include <stdlib.h>

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安裝過程簡單，使用便捷，容易上手，使用者體驗較好。