搭建大型源码阅读环境——使用 OpenGrok

简介: RTFSC 是程序员成长的必修课,营造舒适的环境至关重要。本文介绍了阅读大型源码(如 AOSP)的工具选择,重点推荐了免费开源的 OpenGrok。OpenGrok 提供快速搜索、版本历史查看、语法高亮等功能,适用于特大型项目。文章还详细讲解了 OpenGrok 的安装和配置步骤,帮助读者高效阅读源码。

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

截屏

按惯例先上图吧,万一你一眼就发现不是你的菜呢(截图来自官网)。

搜索功能和源码树:

opengrok-scr1.png

代码导航和版本历史记录:

opengrok-scr2.png

安装和配置

如下以 Windows 下为例,Mac OS X 与 Linux 下与此类似,很多步骤能使用 brew 或者 apt-get 会更方便。

  1. 安装 JDK,并配置 JAVA_HOME 或者 JRE_HOME 环境变量为安装目录。

  2. 下载 Tomcat,解压到一个目录,如 D:\Programs\apache-tomcat-8.5.8,并将此目录添加为 CATALINA_HOME 环境变量。

    catalina-home.png

  3. 下载 Universal Ctags for Windows,将 ctags.exe 文件所在目录添加到 PATH 环境变量。

  4. 下载 OpenGrok 的最新包,比如 opengrok-0.13-rc4.zip,解压到一个目录,如 D:\Programs\opengrok-0.13-rc4。

  5. 配置 data root。

    data root 用于放置生成的索引文件和配置信息,比如我在 OpenGrok 目录下创建了一个 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>
    

    注:这里只是配置一个文件路径,具体的 configuration.xml 会在第 8 步时自动生成。

  7. 配置 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 下的源码。

  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:\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 文件也行啊。

    为大型源码建立索引可能需要漫长的时间,这时候可以去干点别的事了。

  9. 启动 Tomcat,愉快地 RTFSC。

    D:\Programs\apache-tomcat-8.5.8\bin\catalina.bat start
    

    用你最爱的浏览器打开 http://localhost:8080/source/,然后就能愉快地跟 OpenGrok 玩耍了。

    当新添加了项目,或者现有项目有源码更新时,再次执行上一步的命令,就能增量更新索引了。

配置多项目

我曾经为如何在 OpenGrok 里配置多项目苦恼了好久——一开始我是把 Android 源码的根目录当作 source root 的,可想而知 OpenGrok 把 Android 分成了好多个子项目,而这时我也没法再添加新的工程了。

后来才发现建一个专用的 source root,然后把各种项目源码根目录软链接过来,让 OpenGrok 为 source root 下的每个 symbol 一级子目录建立一个项目才是正确的使用方法。

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,还能给源码加标签,写注释等等。

参考:https://www.zhihu.com/question/33505693/answer/132224974

常见问题

打开网页后报错

There was an error!
CONFIGURATION parameter has not been configured in web.xml! Please configure your webapp.
Unable to determine source root path. Missing configuration?
java.io.FileNotFoundException: Unable to determine source root path. Missing configuration?
    at org.opensolaris.opengrok.web.PageConfig.checkSourceRootExistence(PageConfig.java:1562)
    at org.apache.jsp.index_jsp._jspService(index_jsp.java:222)
    at org.apache.jasper.runtime.HttpJspBase.service(HttpJspBase.java:70)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:742)
    at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:443)
    at org.apache.jasper.servlet.JspServlet.serviceJspFile(JspServlet.java:385)
    at org.apache.jasper.servlet.JspServlet.service(JspServlet.java:329)
    at javax.servlet.http.HttpServlet.service(HttpServlet.java:742)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:231)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
    at org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
    at org.opensolaris.opengrok.web.StatisticsFilter.doFilter(StatisticsFilter.java:55)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
    at org.opensolaris.opengrok.web.AuthorizationFilter.doFilter(AuthorizationFilter.java:83)
    at org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilterChain.java:193)
    at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166)
    at org.apache.catalina.core.StandardWrapperValve.invoke(StandardWrapperValve.java:198)
    at org.apache.catalina.core.StandardContextValve.invoke(StandardContextValve.java:96)
    at org.apache.catalina.authenticator.AuthenticatorBase.invoke(AuthenticatorBase.java:478)
    at org.apache.catalina.core.StandardHostValve.invoke(StandardHostValve.java:140)
    at org.apache.catalina.valves.ErrorReportValve.invoke(ErrorReportValve.java:80)
    at org.apache.catalina.valves.AbstractAccessLogValve.invoke(AbstractAccessLogValve.java:624)
    at org.apache.catalina.core.StandardEngineValve.invoke(StandardEngineValve.java:87)
    at org.apache.catalina.connector.CoyoteAdapter.service(CoyoteAdapter.java:342)
    at org.apache.coyote.http11.Http11Processor.service(Http11Processor.java:799)
    at org.apache.coyote.AbstractProcessorLight.process(AbstractProcessorLight.java:66)
    at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:868)
    at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1455)
    at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49)
    at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
    at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)
    at java.lang.Thread.run(Thread.java:745)

这一般是由于更新或切换了 OpenGrok 版本,但却没有将 tomcat 的 webapps 目录下的 source 文件夹替换为对应版本。

后话

古人教会了我们工欲善其事,必先利其器的智慧,但我们也不能沉迷和徘徊于各种利器之间,选择一样自己感觉最称手的工具,把它用熟练,少再在这上面花时间折腾,毕竟把有限的生命投入到无限的 RTFSC 才是正道不是么。

目录
相关文章
|
17天前
|
存储 弹性计算 人工智能
阿里云Alex Chen:普惠计算服务,助力企业创新
本文整理自阿里云弹性计算产品线、存储产品线产品负责人陈起鲲(Alex Chen)在2024云栖大会「弹性计算专场-普惠计算服务,助力企业创新」中的分享。在演讲中,他分享了阿里云弹性计算,如何帮助千行百业的客户在多样化的业务环境和不同的计算能力需求下,实现了成本降低和效率提升的实际案例。同时,基于全面升级的CIPU2.0技术,弹性计算全线产品的性能、稳定性等关键指标得到了全面升级。此外,他还宣布了弹性计算包括:通用计算、加速计算和容器计算的全新产品家族,旨在加速AI与云计算的融合,推动客户的业务创新。
|
24天前
|
存储 人工智能 弹性计算
产品技术能力飞跃,阿里云E-HPC荣获“CCF 产品创新奖”!
9月24日,在中国计算机学会举办的“2024 CCF 全国高性能计算学术年会”中,阿里云弹性高性能计算(E-HPC)荣获「 CCF HPC China 2024 产品创新奖」。这也是继 2022 年之后,阿里云E-HPC 再次荣获此奖项,代表着阿里云在云超算领域的持续创新结果,其产品能力和技术成果得到了业界的一致认可。
|
8天前
|
SQL 人工智能 安全
【灵码助力安全1】——利用通义灵码辅助快速代码审计的最佳实践
本文介绍了作者在数据安全比赛中遇到的一个开源框架的代码审计过程。作者使用了多种工具,特别是“通义灵码”,帮助发现了多个高危漏洞,包括路径遍历、文件上传、目录删除、SQL注入和XSS漏洞。文章详细描述了如何利用这些工具进行漏洞定位和验证,并分享了使用“通义灵码”的心得和体验。最后,作者总结了AI在代码审计中的优势和不足,并展望了未来的发展方向。
|
3天前
|
负载均衡 算法 网络安全
阿里云WoSign SSL证书申请指南_沃通SSL技术文档
阿里云平台WoSign品牌SSL证书是由阿里云合作伙伴沃通CA提供,上线阿里云平台以来,成为阿里云平台热销的国产品牌证书产品,用户在阿里云平台https://www.aliyun.com/product/cas 可直接下单购买WoSign SSL证书,快捷部署到阿里云产品中。
1843 6
阿里云WoSign SSL证书申请指南_沃通SSL技术文档
|
2天前
|
存储 安全 Oracle
【灵码助力安全3】——利用通义灵码辅助智能合约漏洞检测的尝试
本文探讨了智能合约的安全性问题,特别是重入攻击、预言机操纵、整数溢出和时间戳依赖性等常见漏洞。文章通过实例详细分析了重入攻击的原理和防范措施,展示了如何利用通义灵码辅助检测和修复这些漏洞。此外,文章还介绍了最新的研究成果,如GPTScan工具,该工具通过结合大模型和静态分析技术,提高了智能合约漏洞检测的准确性和效率。最后,文章总结了灵码在智能合约安全领域的应用前景,指出尽管存在一些局限性,但其在检测和预防逻辑漏洞方面仍展现出巨大潜力。
|
6天前
|
Web App开发 算法 安全
什么是阿里云WoSign SSL证书?_沃通SSL技术文档
WoSign品牌SSL证书由阿里云平台SSL证书合作伙伴沃通CA提供,上线阿里云平台以来,成为阿里云平台热销的国产品牌证书产品。
1778 2
|
15天前
|
编解码 Java 程序员
写代码还有专业的编程显示器?
写代码已经十个年头了, 一直都是习惯直接用一台Mac电脑写代码 偶尔接一个显示器, 但是可能因为公司配的显示器不怎么样, 还要接转接头 搞得桌面杂乱无章,分辨率也低,感觉屏幕还是Mac自带的看着舒服
|
22天前
|
存储 人工智能 缓存
AI助理直击要害,从繁复中提炼精华——使用CDN加速访问OSS存储的图片
本案例介绍如何利用AI助理快速实现OSS存储的图片接入CDN,以加速图片访问。通过AI助理提炼关键操作步骤,避免在复杂文档中寻找解决方案。主要步骤包括开通CDN、添加加速域名、配置CNAME等。实测显示,接入CDN后图片加载时间显著缩短,验证了加速效果。此方法大幅提高了操作效率,降低了学习成本。
5074 15
|
9天前
|
人工智能 关系型数据库 Serverless
1024,致开发者们——希望和你一起用技术人独有的方式,庆祝你的主场
阿里云开发者社区推出“1024·云上见”程序员节专题活动,包括云上实操、开发者测评和征文三个分会场,提供14个实操活动、3个解决方案、3 个产品方案的测评及征文比赛,旨在帮助开发者提升技能、分享经验,共筑技术梦想。
1034 147
|
17天前
|
存储 缓存 关系型数据库
MySQL事务日志-Redo Log工作原理分析
事务的隔离性和原子性分别通过锁和事务日志实现,而持久性则依赖于事务日志中的`Redo Log`。在MySQL中,`Redo Log`确保已提交事务的数据能持久保存,即使系统崩溃也能通过重做日志恢复数据。其工作原理是记录数据在内存中的更改,待事务提交时写入磁盘。此外,`Redo Log`采用简单的物理日志格式和高效的顺序IO,确保快速提交。通过不同的落盘策略,可在性能和安全性之间做出权衡。
1582 12