浏览Paddle C++源码

四十岁老程序员

在用了五年Go之后，为了浏览Paddle的源码，我重新琢磨如何浏览C++项目的源码。琢磨的结果在这里。

更新

下面方法都实现在这个Github repo里了。

选择工具

在这个Stackoverflow帖子里，大家建议了不少工具。但是基本上大多数建议的upvote都是0。说明其实很多工具都不好用。我记得很多年前Source Insight的用户挺多的。我一直没有用是因为其字体设置实在是太难看了。我用过ctags和cscope，都是经典工具，都可以和Emacs、Vim合用。但是这俩都不是严格按照C++语法来解析源码，并建立索引的。想到最新的科技成果LLVM/Clang衍生出了C++源码的解析工具，我放狗搜了一下，果然有一个工具 woboq codebrowser 利用LLVM/Clang深度解析C++源码并建立索引。试用之后，感觉很满意。

woboq codebrowser

woboq codebrowser的文档里没有解释其工作原理。这里补上。woboq codebrowser是一个C++写的命令行工具，它调用LLVM解析任何一个C++项目的所有源码，然后输出一组HTML文件以及对应的Javascript源码。随后我们可以把这组HTML文件拷贝到某个Web服务器上，就可以在浏览器里浏览C++项目的源码了。比如可以用鼠标点击任何一个symbol，即可跳转到symbol的声明或者定义所在的位置。

为了能解析源码，woboq codebrowser需要知道源码编译的步骤。这些步骤不仅列出了需要关注的源码文件，而且会真的被woboq codebrowser调用的LLVM/Clang执行，从而做宏替换（macro execution）之类的预编译工作，从而得到完备的源码。如果一个C++项目恰好是用CMake来组织的，那么恭喜你，只需要给cmake命令加一个参数，就可以得到这个“编译步骤”，并保存到一个叫compile_commands.json的文件里，方便woboq codebrowser读取。

以下是用woboq codebrowser检索和浏览Paddle的过程。

编译woboq codebrowser

woboq codebrowser支持MacOSX和Linux。Paddle目前只支持Linux。以下步骤都在一个Ubuntu 14.04 VirtualBox VM里进行。

首先安装libclang。这是woboq codebrowser用来解析源码用的。

sudo apt-get update
sudo apt-get install clang-3.8 llvm-3.8 libclang-3.8-dev

随后下载和编译woboq codebrowser

git clone https://github.com/woboq/woboq_codebrowser
cd woboq_codebrowser
cmake . -DLLVM_CONFIG_EXECUTABLE=/usr/bin/llvm-config-3.8 -DCMAKE_BUILD_TYPE=Release
make -j12

编译Paddle

按照Paddle文档里的建议，安装以下软件：

sudo apt-get update
sudo apt-get install -y g++ make cmake build-essential libatlas-base-dev python python-pip libpython-dev m4 libprotobuf-dev protobuf-compiler python-protobuf python-numpy git
sudo apt-get install libgoogle-glog-dev libgflags-dev libgtest-dev
sudo pip install wheel
pushd /usr/src/gtest
cmake . && make
sudo cp *.a /usr/lib
popd

下载Paddle源码。调用cmake时加上-DCMAKE_EXPORT_COMPILE_COMMANDS=ON，这样除了做编译准备，cmake还会输出compile_commands.json，供woboq codebrowser使用：

git clone https://github.com/baidu/paddle
cd paddle
cmake . -DWITH_GPU=OFF -DWITH_DOC=OFF -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

随后编译Paddle。这一步是必须的，因为这个编译过程做一些m4替换生成.proto文件，并且从.proto文件生成对应的C++源码文件。如果我们不做这一步，那么woboq codebrowser会报错说有一些C++源码文件找不到。

make

解析和浏览Paddle

接下来，我们就可以用woboq codebrowser解析Paddle源码，并生成HTML文件了：

OUTPUTDIRECTORY=/vagrant/paddle_html/codebrowser
DATADIRECTORY=$OUTPUTDIRECTORY/../data
BUILDIRECTORY=$PWD
VERSION=`git describe --always --tags`

/vagrant/woboq_codebrowser/generator/codebrowser_generator -b $BUILDIRECTORY -a -o $OUTPUTDIRECTORY -p codebrowser:$BUILDIRECTORY:$VERSION

/vagrant/woboq_codebrowser/indexgenerator/codebrowser_indexgenerator $OUTPUTDIRECTORY

cp -rv /vagrant/woboq_codebrowser/data $DATADIRECTORY

最后，我把 /vagrant/paddle_html 目录scp到租用的一台VPS上，并且在VPS上安装了nginx，就得到了文首的链接。

编辑于 2016-09-21