codebrowser之从浏览器阅读源码

codebrowser能够对源码生成静态HTML网页，搭配nginx可以在WEB上浏览源码。

支持功能如下：

代码跳转。
代码高亮。
代码提示。

下载编译

下载源码：git clone https://github.com/woboq/woboq_codebrowser。

编译命令如下：

sudo apt install llvm clang libclang-dev
cd woboq_codebrowser
mkdir build; cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make

编译内容如下：

~/woboq_codebrowser/build$ cmake -DCMAKE_BUILD_TYPE=Release ..
-- The CXX compiler identification is GNU 11.4.0
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- The C compiler identification is GNU 11.4.0
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/cc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Performing Test HAVE_FFI_CALL
-- Performing Test HAVE_FFI_CALL - Success
-- Found FFI: /usr/lib/x86_64-linux-gnu/libffi.so
-- Performing Test Terminfo_LINKABLE
-- Performing Test Terminfo_LINKABLE - Success
-- Found Terminfo: /usr/lib/x86_64-linux-gnu/libtinfo.so
-- Could NOT find ZLIB (missing: ZLIB_LIBRARY ZLIB_INCLUDE_DIR)
-- Found LibXml2: /usr/lib/x86_64-linux-gnu/libxml2.so (found version "2.9.13")
-- Found LLVM 14.0.0 in /usr/lib/llvm-14
-- Using LLVMConfig.cmake in: /usr/lib/llvm-14/cmake
-- Could NOT find ZLIB (missing: ZLIB_LIBRARY ZLIB_INCLUDE_DIR)
-- Found Clang in /usr/lib/llvm-14
-- Configuring done
-- Generating done
-- Build files have been written to: /home/blduan/woboq_codebrowser/build
~/woboq_codebrowser/build$ make
[  7%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/main.cpp.o
[ 15%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/projectmanager.cpp.o
[ 23%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/annotator.cpp.o
[ 30%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/generator.cpp.o
[ 38%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/preprocessorcallback.cpp.o
[ 46%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/filesystem.cpp.o
[ 53%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/qtsupport.cpp.o
[ 61%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/commenthandler.cpp.o
[ 69%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/projectmanager_systemprojects.cpp.o
[ 76%] Building CXX object generator/CMakeFiles/codebrowser_generator.dir/inlayhintannotator.cpp.o
[ 84%] Linking CXX executable codebrowser_generator
[ 84%] Built target codebrowser_generator
[ 92%] Building CXX object indexgenerator/CMakeFiles/codebrowser_indexgenerator.dir/indexer.cpp.o
[100%] Linking CXX executable codebrowser_indexgenerator
[100%] Built target codebrowser_indexgenerator
~/woboq_codebrowser/build$

使用说明

codebrowser使用分为两步，分别是1使用codebrowser_generator生成HTML文件，2使用codebrowser_indexgenerator对每个HTML文件夹生成索引。

compile_commands.json

codebrowser_generator对代码生成HTML文件时需要依赖于编译配置compile_commands.json，具体生成compile_commands.json文件的方式参考Getting started (llvm.org).

常用的两种CMake与Makefile生成compile_commands.json的方式如下：

cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1
make clean; bear -- make

codebrowser_generator配置选项

$ codebrowser_generator -a -o <output_dir> -b <buld_dir> -p <projectname>:<source_dir>[:<revision>] [-d <data_url>] [-e <remote_path>:<source_dir>:<remote_url>]

选项说明如下：

-a 处理compile_commands.json中的所有文件。如果没有传递这个参数，那么就需要传递要处理的文件列表。
-o 指定文件输出目录。
-b 是指包含compile_commands.json的构建目录。如果没有传递这个参数，编译参数可以在--后通过命令行传递。
-p（一个或多个）用于项目规范。即项目的名称、源代码的绝对路径和用冒号分隔的版本信息。示例：-p projectname:/path/to/source/code:0.3beta。
-d 指定包含所有JavaScript和CSS文件的数据URL。默认为相对于输出目录的../data。示例：-d https://codebrowser.dev/data/。
-e 是对外部项目的引用。示例： -e clang/include/clang:/opt/llvm/include/clang/:https://codebrowser.dev/llvm

codebrowser_indexgenerator配置选项

codebrowser_indexgenerator为上面生成的每个HTML文件目录生成索引。

codebrowser_indexgenerator <output_dir> [-d data_url] [-p project_definition]

选项说明如下：

-p（一个或多个）用于项目规范。即项目的名称、源代码的绝对路径和用冒号分隔的版本信息。示例：-p projectname:/path/to/source/code:0.3beta。
-d 指定包含所有JavaScript和CSS文件的数据URL。默认为相对于输出目录的 ../data。示例：-d https://codebrowser.dev/data/。

示例

我们以paho.mqtt.c-1.3.9作为示例，生成静态HTML文档，然后在本地搭建NGINX静态服务器，并在浏览器上进行查看效果。

codebrowser生成静态HTML

其中的JavaScript与CSS文件来源于woboq_codebrowser源码中自带的data文件夹。

$ ./codebrowser_generator -b paho.mqtt.c-1.3.9/build/ -a -o ./paho.mqtt.c-1.3.9/build/html -p paho.mqtt.c:/home/blduan/paho.mqtt.c-1.3.9:1.3.9 -d ../data
 
$ ./codebrowser_indexgenerator ./paho.mqtt.c-1.3.9/build/html -d ../data

nginx配置

nginx配置如下：

$ cat /etc/nginx/conf.d/paho.mqtt.c.conf
server {
    listen 8081;
    root /home/xxx/paho.mqtt.c-1.3.9/build/html;
    index index.html;
}

页面展示

参考文件

Getting started (llvm.org)

部署 Woboq Code Browser 代码浏览器 - Wings 的博客 (wingszeng.top)

目录