搭建大型源碼閱讀環(huán)境——使用 OpenGrok

來源：極樂科技知乎專欄
作者：mzlogin （極樂科技知乎專欄原創(chuàng)作者）
博客：碼志

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

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

工具的選擇

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

  • IDE

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

  • 編輯器配合插件

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

  • 專門的源碼閱讀工具

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

一類是商業(yè)軟件，比如 Windows 下有著名的 Source Insight，跨平臺的有 Understand，功能都很強(qiáng)大，都是不錯的選擇。當(dāng)然它們都價(jià)格不菲。

而我這里要講的主角 OpenGrok 屬于另一類，免費(fèi)，開源，運(yùn)行流暢，功能也毫不遜色。

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

OpenGrok 特性

譯自官方 Wiki。

  1. OpenGrok 提供如下特性：
  • 快速搜索代碼的引擎
  • 搜索全文、定義、符號、文件路徑和修改歷史
  • 搜索任意指定子目錄（分層搜索）
  • 增量更新索引文件
  • 支持類似 Google 的查詢語法，比如 path:Makefile defs:target
  • 搜索日期范圍內(nèi)修改的文件
  • 支持使用通配符搜索，如 * 表示多個字符，? 表示單個字符
  • 在搜索結(jié)果中展示匹配行
  1. 一個 Web 只讀版的版本歷史查看界面
  • 文件的修改日志
  • 文件在兩個版本間的 diff
  • 文件夾的歷史記錄
  1. 帶語法高亮的交叉引用顯示，可以使用 CSS 自定義樣式
  2. 可以開發(fā)插件支持新的語言和版本控制系統(tǒng)

配置 OpenGrok

截屏

按慣例先上圖吧，萬一你一眼就發(fā)現(xiàn)不是你的菜呢（截圖來自官網(wǎng)）。
搜索功能和源碼樹：


代碼導(dǎo)航和版本歷史記錄：

安裝和配置

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

  1. 安裝 JDK。

  2. 下載 Tomcat，解壓到一個目錄，如 D:\Programs\apache-tomcat-8.5.8。

  3. 下載 Universal Ctags for Windows，將 ctags.exe 文件所在目錄添加到 PATH 環(huán)境變量。

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

  5. 配置 data root。
    data root 用于放置生成的索引文件和配置信息，比如我在 OpenGrok 目錄下創(chuàng)建了一個 data 目錄用作 data root，即 D:\Programs\opengrok-0.13-rc4\data。

  6. 將 OpenGrok 的 lib 目錄里的 source.war 解壓到 D:\Programs\apache-tomcat-8.5.8\webapps\source，配置 WEB-INF\web.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>
  1. 配置 source root。
    可以讓 OpenGrok 認(rèn)為 source root 下的每個子文件夾是一個項(xiàng)目，所以我們利用這個特性來配置和閱讀多個項(xiàng)目源碼就好了。

我的做法是在 OpenGrok 下創(chuàng)建了一個子目錄 D:\Programs\opengrok-0.13-rc4\projects，然后將需要閱讀的源碼使用符號鏈接的方式鏈接到這個目錄里：

cd /d D:\Programs\opengrok-0.13-rc4\projects
mklink /J android D:\sources\android_5.1
mklink /J openjdk7 D:\sources\openjdk7

這樣就有一個叫 android 的工程，它實(shí)際對應(yīng) D:\sources\android_5.1 下的源碼，一個叫 openjdk7 的工程，它實(shí)際對應(yīng) D:\sources\openjdk7 下的源碼。

  1. 建立索引。
    使用 opengrok.jar 調(diào)用 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表示打印操作的進(jìn)度信息。
-s表示指定 source root。
-d表示指定 data root。
-W表示指定將配置寫到該文件。
還有更多配置選項(xiàng)可以使用 java -jar /path/to/opengrok.jar查看。
比如我使用的完整命令行：

java -jar D:\Programs\opengrok-0.13-rc4\lib\opengrok.jar -P -S -v -s D:\Programs\opengrok-0.13-rc4\projects -d D:\Programs\opengrok-0.13-rc4\data -W D:\Programs\opengrok-0.13-rc4\data\configuration.xml

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

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

  1. 啟動 Tomcat，愉快地 RTFSC。
D:\Programs\apache-tomcat-8.5.8\bin\catalina.bat start

用你最愛的瀏覽器打開 http://localhost:8080/source/，然后就能愉快地跟 OpenGrok 玩耍了。
當(dāng)新添加了項(xiàng)目，或者現(xiàn)有項(xiàng)目有源碼更新時(shí)，再次執(zhí)行上一步的命令，就能增量更新索引了。

配置多項(xiàng)目

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

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

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

折騰狂魔

在 Vim 里使用

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

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

在源碼里做筆記

配合 Chrome 插件 Diigo，還能給源碼加標(biāo)簽，寫注釋等等。
參考：https://www.zhihu.com/question/33505693/answer/132224974

后話

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

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容