关于可视化:聊聊代码仓库可视化gource-篇

本篇文章将聊聊如何高效的将代码仓库中的提交记录和目录构造，疾速转变为“酷炫的视频”。分享如何应用 Docker 在不同 CPU 架构的设施上运行 gource，以及如何基于最新的 M1 Pro 芯片的设施，让制作可视化视频的效率成倍晋升。

写在后面

前一阵为了庆贺社区我的项目 Milvus 在 GitHub 取得了一万颗星星，我制作了一个视频，用来动静的展现在过来的工夫里，这个我的项目的具体提交情况和我的项目组织架构变动情况。

最近有共事聊开源我的项目的“保护血泪史”时，又提到了这件事。勾起了我过后制作视频的苦楚回顾：过后的视频制作计划是应用 docker 运行 gource。在针对诸如 Milvus 仓库这种提交量比拟大的仓库时（1.4万提交），想要生成可视化视频，应用我手头的 i9 处理器的设施，至多须要跑个把小时。而当我将雷同的操作换到 M1 设施（M1 Pro）运行后，或者是因为 docker 中的利用并未针对 ARM 芯片做优化、又或者是 docker 中的程序版本不够新，雷同的工作量，甚至须要跑半天能力搞定！
不论如何，这个后果未免太不迷信了。

且不说 M1 的运行后果“出其不意”，但就是个把小时的视频生成工夫，也让我感觉挺不难受的。作为一个谋求效率的老程序员，我花了一些工夫，终于摸索出了这个问题的“正确答案”：如果应用针对 M1 芯片而编译的程序，整个视频的生成工夫能够缩短到半个小时左右，相比拟之前晋升成果颇为显著。

在开展聊聊我是如何做的之前，我想先介绍一下 gource 这款开源软件。

对于 Gource

2009 年，来自新西兰的工程师 Andrew Caudwell，心愿可能将各种代码版本管理软件的信息可视化，于是他应用 C++ 编写了 Gource 这个程序。2011 年，我的项目从 Google Code 迁徙至 GitHub 后，我的项目开启了年更模式。

比拟侥幸的是，截止本文成文写出的时候，软件曾经公布了往年的两个重要更新：蕴含视网膜屏幕的反对，以及针对字体缩放性能进行了大量修改，并将软件应用的正则库降级为了 PCRE2，程序版本更新到了 0.53 。

因为我的项目在 GitHub 发布页面中只提供了 Windows 版本的程序，所以如果咱们想获取 Linux / macOS 的新版本程序，就只能本人进行编译啦。（Ubuntu APT 仓库中的版本还停留在 2019 年公布的 0.51）

接下来，咱们先来聊聊如何进行编译，如果你心愿应用 Docker 或 x86 设施，能够浏览本文前面的章节。

在 M1 设施上进行 Gource 的编译

为了可能在 macOS 上实现新版本的程序编译，咱们须要先实现 gource 的依赖装置：

brew install pkg-config freetype2 pcre2 glow sdl2 sdl2_image boost glm autoconf

如果你没有实现上述依赖的装置，那么在执行 ./configure 的时候，肯定会遇到诸如上面的问题：

checking for FT2... configure: error: in `/Users/soulteary/lab/gource-0.53':configure: error: The pkg-config script could not be found or is too old.  Make sure itis in your PATH or set the PKG_CONFIG environment variable to the fullpath to pkg-config....No package 'libpcre2-8' found...

当咱们装置结束依赖之后，还须要配置一下编译参数，让程序在编译的时候可能找到咱们刚刚装置的依赖。不然，就会呈现相似上面的谬误：

checking for boostlib >= 1.46 (104600)... configure: We could not detect the boost libraries (version 1.46 or higher). If you have a staged boost library (still not installed) please specify $BOOST_ROOT in your environment and do not give a PATH to --with-boost option.  If you are sure you have boost installed, then check your version number looking in <boost/version.hpp>. See http://randspringer.de/boost for more documentation.configure: error: Boost Filesystem >= 1.46 is required. Please see INSTALL...configure: error: GLM headers are required. Please see INSTALL...

对于 boost 框架，咱们能够通过简略应用 --with-boost 参数来指定依赖的目录，而对于 glm（OpenGL Mathematics），因为它是一个仅蕴含头文件的数学库，所以咱们必须应用 CPPFLAGS 等参数，将门路传递给 configure。

然而咱们要如何在 macOS 中取得由 brew 装置的 glm 或 boost 门路呢？这里能够将上面两种办法进行组合应用。

第一种查找门路的办法是应用 brew list 命令，获取咱们装置的某个软件的具体目录列表，在输入日志中寻找或尝试出正确的目录。以 boost 举例，当咱们执行结束 brew list boost 之后，可能看到相似上面的输入后果：

/opt/homebrew/Cellar/boost/1.78.0_1/include/boost/ (15026 files)/opt/homebrew/Cellar/boost/1.78.0_1/lib/libboost_atomic-mt.dylib/opt/homebrew/Cellar/boost/1.78.0_1/lib/libboost_chrono-mt.dylib...

其中 /opt/homebrew/Cellar/boost/1.78.0_1/ 就是 boost 的根目录，将这个门路拼合为 --with-boost=/opt/homebrew/Cellar/boost/1.78.0_1/ 参数，而后就可能在编译中应用 boost 啦。

第二种门路的查找办法，是应用 pkg-config 工具，输入 C++ 我的项目编译能够应用的具体目录参数。特地适宜 glm 这类我的项目。咱们通过为 pkg-config 增加参数，能够失去命令 pkg-config glm --libs --cflags，当命令执行结束，就可能失去编译时能够间接应用的目录地址了：

-I/opt/homebrew/Cellar/glm/0.9.9.8/include

将下面的参数进行整合，不难失去在 M1 设施上的进行编译配置的残缺命令：

./configure --with-boost=/opt/homebrew/Cellar/boost/1.78.0_1/ CPPFLAGS="-I/opt/homebrew/Cellar/glm/0.9.9.8/include"

当命令执行结束，不出意外，咱们将看到相似上面的日志输入：

checking for a BSD-compatible install... /usr/bin/install -cchecking whether build environment is sane... yeschecking for a thread-safe mkdir -p... build-aux/install-sh -c -dchecking for gawk... nochecking for mawk... nochecking for nawk... nochecking for awk... awkchecking whether make sets $(MAKE)... yeschecking whether make supports nested variables... yeschecking build system type... arm-apple-darwin21.4.0checking host system type... arm-apple-darwin21.4.0checking for g++... g++checking whether the C++ compiler works... yeschecking for C++ compiler default output file name... a.outchecking for suffix of executables... checking whether we are cross compiling... nochecking for suffix of object files... ochecking whether we are using the GNU C++ compiler... yeschecking whether g++ accepts -g... yeschecking for style of include used by make... GNUchecking dependency style of g++... gcc3checking for timegm... yeschecking for unsetenv... yeschecking how to run the C++ preprocessor... g++ -Echecking for X... disabledchecking for a sed that does not truncate output... /usr/bin/sedchecking for gcc... gccchecking whether we are using the GNU C compiler... yeschecking whether gcc accepts -g... yeschecking for gcc option to accept ISO C89... none neededchecking whether gcc understands -c and -o together... yeschecking dependency style of gcc... gcc3checking for the pthreads library -lpthreads... nochecking whether pthreads work without any flags... yeschecking for joinable pthread attribute... PTHREAD_CREATE_JOINABLEchecking if more special flags are required for pthreads... -D_THREAD_SAFEchecking how to run the C preprocessor... gcc -Echecking for grep that handles long lines and -e... /usr/bin/grepchecking for egrep... /usr/bin/grep -Echecking for ANSI C header files... yeschecking for sys/types.h... yeschecking for sys/stat.h... yeschecking for stdlib.h... yeschecking for string.h... yeschecking for memory.h... yeschecking for strings.h... yeschecking for inttypes.h... yeschecking for stdint.h... yeschecking for unistd.h... yeschecking whether we are using the Microsoft C compiler... nochecking windows.h usability... nochecking windows.h presence... nochecking for windows.h... nochecking for GL/gl.h... nochecking for OpenGL/gl.h... yeschecking for OpenGL library... -framework OpenGLchecking for GL/glu.h... nochecking for OpenGL/glu.h... yeschecking for OpenGL Utility library... yeschecking for varargs GLU tesselator callback function type... nochecking for pkg-config... /opt/homebrew/bin/pkg-configchecking pkg-config is at least version 0.9.0... yeschecking for FT2... yeschecking for PCRE2... yeschecking for GLEW... yeschecking for SDL2... yeschecking for PNG... yeschecking for IMG_LoadPNG_RW... yeschecking for IMG_LoadJPG_RW... yeschecking for boostlib >= 1.46 (104600) includes in "/opt/homebrew/Cellar/boost/1.78.0_1//include"... yeschecking for boostlib >= 1.46 (104600) lib path in "/opt/homebrew/Cellar/boost/1.78.0_1//lib/arm-darwin21.4.0"... nochecking for boostlib >= 1.46 (104600) lib path in "/opt/homebrew/Cellar/boost/1.78.0_1//lib"... yeschecking for boostlib >= 1.46 (104600)... yeschecking whether the Boost::System library is available... yeschecking for exit in -lboost_system... yeschecking whether the Boost::Filesystem library is available... yeschecking for exit in -lboost_filesystem... yeschecking glm/glm.hpp usability... yeschecking glm/glm.hpp presence... yeschecking for glm/glm.hpp... yeschecking that generated files are newer than configure... doneconfigure: creating ./config.statusconfig.status: creating Makefileconfig.status: executing depfiles commands

接下来，执行 make ，零碎就会开始对 gource 进行编译，在编译实现之后，接着执行 sudo make install，gource 的编译平安就完结啦。

在 M1 设施上应用 Gource 进行代码仓库可视化

在应用 gource 制作视频前，咱们须要评估我的项目所需的硬盘空间，生成视频的尺寸和仓库的提交量（commits）、总的文件目录数量、我的项目保护工夫长，都有很大关系，这里以前文中提到的 Milvus 仓库为例。

这个仓库从 2019 年开始保护，截止以后有 1.4 万次提交，如果想咱们生成 1280x720 尺寸的视频内容，假如将我的项目每天的提交数据展现的工夫设置为 1 秒，过程中将输入 370 多 GB 的临时文件（PPM 截图文件），所以在开始进行仓库可视化之前，请确认你的硬盘留有足够的空间。

下载要进行可视化的代码仓库

可视化的第一步，是将咱们要可视化的仓库下载到本地，比方：

git clone https://github.com/milvus-io/milvus.git

应用 Gource 进行可视化渲染

接下来，咱们须要应用 gource 指定咱们将来心愿失去的视频的最大分辨率，以及一些要害细节：

咱们心愿这个视频中，每一天的展现工夫为多久（本例为1秒）
咱们心愿这个视频中，视频的最大帧率是多少（本例为30帧）
咱们心愿输入的文件名和刚刚应用 git clone 下载好的仓库的目录名是什么

gource --viewport 1280x720 \    --high-dpi \    --seconds-per-day 1 \    --output-ppm-stream milvus.ppm \    --output-framerate 30 \    milvus

执行下面的命令，程序将会关上一个预览界面，开始将仓库的每一次提交记录和过后的目录构造进行可视化绘制。

通过绝对漫长的期待之后（19分钟左右），当命令执行结束，咱们就失去了蕴含所有代码仓库提交信息、目录变动信息的临时文件：milvus.ppm。

应用 ffmpeg 生成最终的视频文件

咱们在上一步失去的文件，足足有 370 GB 之大。为了失去一个不便后续剪辑或在各种网络平台上流传的文件，咱们还须要应用 ffmpeg 对其进行格局转换。

如果你没有装置过 ffmpeg，能够思考应用上面的命令实现装置（本文应用版本为 5.0.1）。

brew install ffmpeg

想要生成一个兼容性比拟好的 H264 格局的 milvus.mp4 文件，能够应用上面的命令：

ffmpeg -y -r 30 -f image2pipe -loglevel info -vcodec ppm -i ./milvus.ppm -vcodec libx264 -preset medium -pix_fmt yuv420p -crf 1 -threads 0 -bf 0 ./milvus.mp4

急躁期待命令执行结束（14分钟左右），咱们就可能失去蕴含酷炫后果的视频文件啦。相比拟上一步骤中的 370GB 临时文件，视频文件显得绝对玲珑，只须要 12GB 左右的空间。

应用 Docker 进行代码仓库的可视化

如果你不谋求更高的转换效率，能够承受“离线工作”的执行形式，能够思考应用开源我的项目 sandrokeil/docker-files/ 中的 gource 镜像。

应用办法非常简单，只须要一条命令：

docker run --rm -it -v `pwd`/repo:/repos -v `pwd`/results:/results -v `pwd`/avatars:/avatars -v `pwd`/mp3s:/mp3s sandrokeil/gource:latest

在下面的命令中，咱们须要做一些简略的筹备：

把咱们的代码仓库搁置于当前目录下的 repo 目录中。
将咱们打算进行代替的用户头像放在 avatars 目录中。
如果你心愿程序生成视频的过程中，顺带实现背景音的配乐，能够将 mp3 文件放在 mp3s 目录中。

当命令执行结束之后，咱们就可能在本地的 results 目录中找到咱们的可视化视频文件了。

其余

除了忠诚还原仓库中的每一次提交之外，Gource 还反对依据参数筛选工夫启止、筛选生成指定用户的奉献记录、甚至搭配 shell 能够筛选生成指定目录的变动记录。

所以，当咱们想进行某个大版本回顾，或者庆贺某位开源社区的用户成为我的项目 maintainer 时，把这些“混杂着代码的工夫碎片”通过视频进行还原出现，或者是一个不错的主见。

最初

心愿这篇内容可能帮到有雷同需要的你。

下一篇雷同主题的内容，我将分享 gource 之外的我的项目可视化计划，一个绝对轻量的计划。

--EOF

本文应用「署名 4.0 国内 (CC BY 4.0)」许可协定，欢送转载、或从新批改应用，但须要注明起源。署名 4.0 国内 (CC BY 4.0)

本文作者: 苏洋

创立工夫: 2022年05月10日
统计字数: 8873字
浏览工夫: 18分钟浏览
本文链接: https://soulteary.com/2022/05...