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

時間 2019-11-17

標籤搭建大型源碼閱讀環境使用 opengrok 简体版

原文原文鏈接

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

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

工具的選擇

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

IDE程序員

在看特定類型項目時這是個人首選。好比它本來就是一個 Visual Studio 工程，那固然用 Visual Studio 來打開閱讀，看 Android App 或者 Library 源碼固然用 Android Studio 體驗更好。github
編輯器配合插件web

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

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

一類是商業軟件，好比 Windows 下有著名的 Source Insight，跨平臺的有 Understand，功能都很強大，都是不錯的選擇。固然它們都價格不菲。瀏覽器

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

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

OpenGrok 特性

譯自官方 Wiki。

OpenGrok 提供以下特性：

快速搜索代碼的引擎
- 搜索全文、定義、符號、文件路徑和修改歷史
- 搜索任意指定子目錄（分層搜索）
- 增量更新索引文件
- 支持相似 Google 的查詢語法，好比 path:Makefile defs:target
- 搜索日期範圍內修改的文件
- 支持使用通配符搜索，如 * 表示多個字符，? 表示單個字符
- 在搜索結果中展現匹配行
一個 Web 只讀版的版本歷史查看界面
- 文件的修改日誌
- 文件在兩個版本間的 diff
- 文件夾的歷史記錄
帶語法高亮的交叉引用顯示，可使用 CSS 自定義樣式
能夠開發插件支持新的語言和版本控制系統

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

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

配置 OpenGrok

截屏

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

搜索功能和源碼樹：

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

安裝和配置

以下以 Windows 下爲例，Mac OS X 與 Linux 下與此相似，不少步驟能使用 brew 或者 apt-get 會更方便。

安裝 JDK，並配置 JAVA_HOME 或者 JRE_HOME 環境變量爲安裝目錄。
下載 Tomcat，解壓到一個目錄，如 D:\Programs\apache-tomcat-8.5.8，並將此目錄添加爲 CATALINA_HOME 環境變量。
下載 Universal Ctags for Windows，將 ctags.exe 文件所在目錄添加到 PATH 環境變量。
下載 OpenGrok 的最新包，好比 opengrok-0.13-rc4.zip，解壓到一個目錄，如 D:\Programs\opengrok-0.13-rc4。
配置 data root。

data root 用於放置生成的索引文件和配置信息，好比我在 OpenGrok 目錄下建立了一個 data 目錄用做 data root，即 D:\Programs\opengrok-0.13-rc4\data。

將 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>複製代碼

配置 source root。

可讓 OpenGrok 認爲 source root 下的每一個子文件夾是一個項目，因此咱們利用這個特性來配置和閱讀多個項目源碼就行了。

個人作法是在 OpenGrok 下建立了一個子目錄 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 的工程，它實際對應 D:\sources\android_5.1 下的源碼，一個叫 openjdk7 的工程，它實際對應 D:\sources\openjdk7 下的源碼。
創建索引。

使用 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:\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複製代碼
```
每次須要創建或更新索引的時候敲這麼長一個命令固然很不爽，使用 doskey 或者 Cmder 裏的 alias 命令將其 alias 爲 opengrok-index 命令會省力很多，再不濟把這命令存成個 bat 文件也行啊。

爲大型源碼創建索引可能須要漫長的時間，這時候能夠去幹點別的事了。
啓動 Tomcat，愉快地 RTFSC。
```
D:\Programs\apache-tomcat-8.5.8\bin\catalina.bat start複製代碼
```
用你最愛的瀏覽器打開 http://localhost:8080/source/，而後就能愉快地跟 OpenGrok 玩耍了。

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