標籤：

搭建大型源碼閱讀環境——使用 OpenGrok

01-26

RTFSC 是程序員打怪升級路上避不開的功課，那營造一個舒適的環境來提升上課的體驗就很有必要了。

比如閱讀 AOSP 這種大型源碼，用什麼姿勢來閱讀才能絲般順滑，讓 F**king Source Code 也變得不那麼可惡呢？

工具的選擇

閱讀源碼的工具我嘗試過以下幾類：

  1. IDE

    在看特定類型項目時這是我的首選。比如它原本就是一個 Visual Studio 工程，那當然用 Visual Studio 來打開閱讀，看 Android App 或者 Library 源碼當然用 Android Studio 體驗更好。

  2. 編輯器配合插件

    比如 Vim + Ctags + Cscope，再配合文件模糊查找插件 LeaderF 和神器 YouCompleteMe，在源碼規模不大時很方便，打開也輕快，閱讀一些小項目時我還是樂意使用它們。

  3. 專門的源碼閱讀工具

    在針對特大型源碼時，比如 AOSP 和 Chromium，使用上述兩種方案可能會感覺乏力，這時候就需要祭出專門的源碼閱讀工具了。

    一類是商業軟體，比如 Windows 下有著名的 Source Insight，跨平台的有 Understand，功能都很強大，都是不錯的選擇。當然它們都價格不菲。

    而我這裡要講的主角 OpenGrok 屬於另一類，免費，開源，運行流暢，功能也毫不遜色。

如果你還在尋覓適合你自己的解決方案，大可以花一點時間將以上幾種都嘗試一遍，哪個稱手用哪個，也可以像我一樣，針對不同的項目使用不同的工具。想直觀了解 OpenGrok 的同學可以直接先看看一些使用 OpenGrok 的在線源碼查看網站，看看它能否滿足你的需求，其中的一些列在 OpenGrok installations。

OpenGrok 特性

譯自官方 Wiki。

OpenGrok 提供如下特性：

  1. 快速搜索代碼的引擎

    • 搜索全文、定義、符號、文件路徑和修改歷史

    • 搜索任意指定子目錄（分層搜索）

    • 增量更新索引文件

    • 支持類似 Google 的查詢語法，比如 path:Makefile defs:target

    • 搜索日期範圍內修改的文件

    • 支持使用通配符搜索，如 * 表示多個字元，? 表示單個字元

    • 在搜索結果中展示匹配行

  2. 一個 Web 只讀版的版本歷史查看界面

    • 文件的修改日誌

    • 文件在兩個版本間的 diff

    • 文件夾的歷史記錄

  3. 帶語法高亮的交叉引用顯示，可以使用 CSS 自定義樣式

  4. 可以開發插件支持新的語言和版本控制系統

    已經支持的語言： Supported Languages and Formats

    已經支持的版本控制系統：Supported Revision Control Systems

配置 OpenGrok

截屏

按慣例先上圖吧，萬一你一眼就發現不是你的菜呢（截圖來自官網）。

搜索功能和源碼樹：

代碼導航和版本歷史記錄：

安裝和配置

如下以 Windows 下為例，Mac OS X 與 Linux 下與此類似，很多步驟能使用 brew 或者 apt-get 會更方便。

  1. 安裝 JDK，並配置 JAVA_HOME 或者 JRE_HOME 環境變數為安裝目錄。

  2. 下載 Tomcat，解壓到一個目錄，如 D:Programsapache-tomcat-8.5.8，並將此目錄添加為 CATALINA_HOME 環境變數。

  3. 下載 Universal Ctags for Windows，將 ctags.exe 文件所在目錄添加到 PATH 環境變數。

  4. 下載 OpenGrok 的最新包，比如 opengrok-0.13-rc4.zip，解壓到一個目錄，如 D:Programsopengrok-0.13-rc4。

  5. 配置 data root。

    data root 用於放置生成的索引文件和配置信息，比如我在 OpenGrok 目錄下創建了一個 data 目錄用作 data root，即 D:Programsopengrok-0.13-rc4data。

  6. 將 OpenGrok 的 lib 目錄里的 source.war 解壓到 D:Programsapache-tomcat-8.5.8webappssource，配置 WEB-INFweb.xml 文件的 CONFIGURATION 為上一步生成的 data 目錄下的 configureation.xml，比如我的配置：

    <display-name>OpenGrok</display-name><description>A wicked fast source browser</description><context-param> <description>Full path to the configuration file where OpenGrok can read its configuration</description> <param-name>CONFIGURATION</param-name> <param-value>D:/Programs/opengrok-0.13-rc4/data/configuration.xml</param-value></context-param>

  7. 配置 source root。

    可以讓 OpenGrok 認為 source root 下的每個子文件夾是一個項目，所以我們利用這個特性來配置和閱讀多個項目源碼就好了。

    我的做法是在 OpenGrok 下創建了一個子目錄 D:Programsopengrok-0.13-rc4projects，然後將需要閱讀的源碼使用符號鏈接的方式鏈接到這個目錄里：

    cd /d D:Programsopengrok-0.13-rc4projectsmklink /J android D:sourcesandroid_5.1mklink /J openjdk7 D:sourcesopenjdk7

    這樣就有一個叫 android 的工程，它實際對應 D:sourcesandroid_5.1 下的源碼，一個叫 openjdk7 的工程，它實際對應 D:sourcesopenjdk7 下的源碼。

  8. 建立索引。

    使用 opengrok.jar 調用 ctags 來為源碼建立索引。命令行：

    java -jar /path/to/opengrok.jar -P -S -v -s /path/to/source/root -d /path/to/data/root -W /path/to/configuration.xml

    -P 表示為 source root 目錄下的每個一級子目錄生成一個工程。

    -S 表示搜索並添加 「external」 source repositories。

    -v 表示列印操作的進度信息。

    -s 表示指定 source root。

    -d 表示指定 data root。

    -W 表示指定將配置寫到該文件。

    還有更多配置選項可以使用 java -jar /path/to/opengrok.jar 查看。

    比如我使用的完整命令行：

    java -jar D:Programsopengrok-0.13-rc4libopengrok.jar -P -S -v -s D:Programsopengrok-0.13-rc4projects -d D:Programsopengrok-0.13-rc4data -W D:Programsopengrok-0.13-rc4dataconfiguration.xml

    每次需要建立或更新索引的時候敲這麼長一個命令當然很不爽，使用 doskey 或者 Cmder 里的 alias 命令將其 alias 為 opengrok-index 命令會省力不少，再不濟把這命令存成個 bat 文件也行啊。

    為大型源碼建立索引可能需要漫長的時間，這時候可以去干點別的事了。

  9. 啟動 Tomcat，愉快地 RTFSC。

    D:Programsapache-tomcat-8.5.8incatalina.bat start

    用你最愛的瀏覽器打開 localhost:8080/source/，然後就能愉快地跟 OpenGrok 玩耍了。

    當新添加了項目，或者現有項目有源碼更新時，再次執行上一步的命令，就能增量更新索引了。

配置多項目

我曾經為如何在 OpenGrok 里配置多項目苦惱了好久——一開始我是把 Android 源碼的根目錄當作 source root 的，可想而知 OpenGrok 把 Android 分成了好多個子項目，而這時我也沒法再添加新的工程了。

後來才發現建一個專用的 source root，然後把各種項目源碼根目錄軟鏈接過來，讓 OpenGrok 為 source root 下的每個 symbol 一級子目錄建立一個項目才是正確的使用方法。

Windows 下建立軟鏈接的方法是使用 mklink /J android D:sourcesandroid_5.1，Mac OS X 和 Linux 下可以使用 ln -s /path/to/source project_name。

折騰狂魔

在 Vim 里使用

沒錯，還有人做了支持在 Vim 里使用 OpenGrok 的插件，如果你是 Vim 控+折騰狂魔，可以一試，這裡僅給出插件地址：

asenac/vim-opengrokjdevera/vim-opengrok-search

反正像我這種智商是折騰不動了，就安心在瀏覽器里用了。

在源碼里做筆記

配合 Chrome 插件 Diigo，還能給源碼加標籤，寫注釋等等。

參考：有哪些不錯的大型項目代碼瀏覽工具？ - 韋易笑的回答 - 知乎

後話

古人教會了我們工欲善其事，必先利其器的智慧，但我們也不能沉迷和徘徊於各種利器之間，選擇一樣自己感覺最稱手的工具，把它用熟練，少再在這上面花時間折騰，畢竟把有限的生命投入到無限的 RTFSC 才是正道不是么。

推薦閱讀：

※Android 源碼編譯後，怎麼發布到真機？
※Xposed帶我用上真正的安卓機
※MIUI主題製作賺錢嗎？
※為什麼許多廠商喜歡魔改 AOSP？
※小米MIUI有哪些好的主題推薦？

TAG:源码阅读 | Android |