企业官网建设流程全解析

• 音视频
• 视频处理
• 图形学
• 桌面应用

本指南围绕 Natron 开源合成软件仓库中的 tools/README.md 展开，系统梳理 Natron 官方用于跨平台构建、依赖打包、文档生成、CI 持续集成与代码维护的整套工具链。你将掌握如何复用tools目录下的脚本完成 Linux/Windows/macOS 的 SDK 构建、静态文档生成、MSYS2/MacPorts 依赖更新，以及代码格式化与许可合规检查等实战能力。

一、tools 目录总览：Natron 工程化维护的“工具箱”

tools目录是 Natron 仓库中专用于“构建与维护 Natron 自身”的辅助工具集合，与 Engine、Gui 等核心运行时代码相互独立。目录中既包含生成随二进制分发的 HTML 文档的脚本，也包含为 Jenkins 等 CI 平台准备的构建脚本、为 macOS 的 MacPorts 与 Windows 的 MSYS2 维护的专属软件包配方，以及代码格式化、资源清理等日常维护工具。

从目录结构看，它由以下部分组成：

二、MacPorts：维护 macOS 专属依赖配方

tools/MacPorts 存放的是Natron 专用的 MacPorts 端口（port）配方。之所以需要这套专属配方，是因为部分依赖并未进入官方 MacPorts 仓库（例如 openimageio），另一些则需要额外补丁解决特定问题（如许可证合规、universal 构建等）。

2.1 Portfile 三件套的约定

每个端口目录下，除Portfile本身外，还同时存放：

• Portfile.orig：原始官方 MacPortsPortfile的备份；
• Portfile.patch：Natron 对该Portfile应用的补丁。

这种“原文件 + 补丁”的组织方式，使得在sudo port selfupdate后能够快速对比官方版本与本仓库版本之间的差异。

2.2 check.sh：检测哪些 Portfile 需要更新

tools/MacPorts/check.sh 用于检查Portfile是否已落后于 MacPorts 官方仓库。其核心逻辑如下：

• 从/opt/local/var/macports/sources/rsync.macports.org/release/tarballs/ports（或macports/release/tarballs/ports）定位已同步的官方端口树；
• 遍历本目录下所有Portfile：若存在Portfile.orig，则与官方版本执行diff -q比较；若文件内容有差异或官方版本更新，即判定为obsolete；
• 对过时条目打印提示与建议命令，例如cp <官方 Portfile> <本地 Portfile.orig>; cp <官方 Portfile> <本地 Portfile>; (cd 目录 && patch < Portfile.patch)；
• 同时递归检查files/子目录中的补丁文件是否缺失或过时。

用法为在tools/MacPorts目录下直接执行./check.sh。结合 tools/MacPorts/README.txt，还可以将本目录注册为 MacPorts 的本地源：在/opt/local/etc/macports/sources.conf文件头部加入file:///Users/USER_NAME/Development/Natron/tools/MacPorts（注意是三个斜杠的file:///），然后执行sudo port selfupdate，最后在本地目录运行portindex重建索引。

三、genStaticDocs.sh：生成随二进制分发的静态文档

tools/genStaticDocs.sh 是生成Natron HTML 文档的关键脚本——这些文档最终随 Natron 二进制包一起分发。该脚本由 buildmaster 与 jenkins 脚本调用，也可以在撰写文档期间手动运行以预览效果。

3.1 依赖与前置条件

脚本要求系统中已安装pandoc（用于 Markdown 转 reStructuredText）与Sphinx（用于最终构建 HTML）。脚本内部还会做 pandoc 版本检查：由于 pandoc 2.4 起无法强制在 rst 输出中使用 grid tables（参见 pandoc 官方 issue #5393），因此当检测到 pandoc 版本高于 2.3.1 时脚本会直接退出并提示改用 2.3.1。从源码看，这一限制与 Engine/Node.cpp 中Node::makeDocumentation()及convertFromPlainTextToMarkdown()的“multiline table element hack”实现相互关联。

3.2 完整用法示例（macOS）

在 macOS 上，若 Natron snapshot 或 release 已安装为/Applications/Natron.app，可按如下步骤生成静态文档到html子目录：

cd <Natron source directory>/Documentation natron="/Applications/Natron.app" env FONTCONFIG_FILE="$natron/Contents/Resources/etc/fonts/fonts.conf" \ OCIO="$natron/Contents/Resources/OpenColorIO-Configs/blender/config.ocio" \ OFX_PLUGIN_PATH="$natron/Contents/Plugins" \ NATRON_PLUGIN_PATH="$natron/Contents/Plugins/PyPlugs" \ bash ../tools/genStaticDocs.sh "$natron/Contents/MacOS/NatronRenderer" /var/tmp/natrondocs . sphinx-build -b html source html

脚本接受三个位置参数：

1. NATRON_BIN：NatronRenderer可执行文件路径（必须使用 snapshot 构建）；
2. TMP_FOLDER：存放中间 Markdown/RST 文件的临时目录；
3. DOC_FOLDER：Natron 的Documentation源码目录。

3.3 脚本内部流程

从 tools/genStaticDocs.sh 源码可以还原完整工作流：

1. 清理$DOC_FOLDER/source下旧的_group*、_prefs.rst与plugins目录；
2. 若设置了OFX_PLUGIN_PATH，自动附加--setting useStdOFXPluginsLocation=False启动选项；
3. 用--export-docs "$TMP_FOLDER"调用NatronRenderer导出所有插件文档（Markdown 格式）到临时目录；
4. 对每个.md文件执行pandoc -f markdown -t rst-simple_tables-multiline_tables+grid_tables --columns=9000转为 RST；
5. 对ReadOIIO/WriteOIIO等插件文档做 pandoc 星号转义修复；
6. 对插件 RST 文件插入.. _插件名:锚点标签、为 Controls 表格添加.. tabularcolumns::与.. cssclass:: longtable属性；
7. 将生成的.rst与.png图片拷贝回$DOC_FOLDER/source与$DOC_FOLDER/source/plugins，供 Sphinx 构建。

生成完成后，临时文件仍保留在$TMP_FOLDER中，可安全删除。

四、jenkins：面向 CI 的构建与测试脚本

tools/jenkins 是 Natron 在 Linux、Windows、macOS 三平台上的Jenkins 持续集成工具集，承担从 SDK 构建到单元测试、产物归档的完整流水线。

4.1 SDK 构建

Linux（32 位与 64 位通用）：执行 tools/jenkins/include/scripts/build-Linux-sdk.sh（目录中为include/scripts/build-Linux-sdk.sh），该脚本会构建并安装 Natron 的全部依赖到/opt/Natron-sdk（要求该目录对当前用户可写），其中包括打过补丁的 Qt4、mangled OSMesa（基于 LLVM 4.0.1）、OpenImageIO 以及其余全部依赖。

Windows 7（已安装 MSYS2）：执行 tools/jenkins/include/scripts/build-Windows-sdk.sh：

MSYSTEM=MINGW64 BITS=64 ./include/scripts/build-Windows-sdk.sh # 64 位 MSYSTEM=MINGW32 BITS=32 ./include/scripts/build-Windows-sdk.sh # 32 位

4.2 Windows 环境的常规更新流程

文档强调 Windows 构建系统需要定期更新，更新顺序如下：

1. 从官方 MINGW-packages 仓库的本地 clone 拉取更新；
2. 进入 Natron 源码的tools/MINGW-packages目录执行./check.sh，查看哪些软件包需要更新，并相应更新这些包的PKGCONFIG；
3. 执行pacman -Syu更新 MSYS2——当提示替换 x264 包时，对以下两个问题均回答n：

:: Replace mingw-w64-i686-x264 with mingw32/mingw-w64-i686-x264-git? [Y/n] n :: Replace mingw-w64-x86_64-x264 with mingw64/mingw-w64-x86_64-x264-git? [Y/n] n

执行后pacman -Syu可能要求关闭并重新打开终端； 4. 再次执行MSYSTEM=MINGW64 BITS=64 ./include/scripts/build-Windows-sdk.sh重新构建并安装 Natron 专属软件包。

4.3 平台启动脚本与单元测试

• macOS 10.9：macStartupJenkins.sh；
• Linux CentOS 6.4（32 位与 64 位）：linuxStartupJenkins.sh；
• Windows 10（32 位与 64 位）：winStartupJenkins.bat。

这些脚本负责构建 Natron 二进制并执行单元测试，本质上是 tools/buildmaster 目录中旧脚本的更新版本（README 注明它们并未被用于产出正式 release，且 macOS 脚本在 10.9 上不会生成 32/64 位通用二进制）。

4.4 launchBuildMain.sh：统一构建入口与参数

tools/jenkins/launchBuildMain.sh 是新一代的构建主脚本，不依赖外部数据库即可直接以环境变量方式调用，专门面向 Jenkins CI 基础设施设计。其核心环境变量参数如下（详见 tools/jenkins/README.md）：

典型调用示例：

NATRON_LICENSE=GPL GIT_URL=<Natron 仓库地址> GIT_BRANCH=master GIT_COMMIT=f7ee2a2c43bd0de9fc8d3776346408dd4f43426b \ UNIT_TESTS=true BUILD_NUMBER=1 BUILD_NAME=test COMPILE_TYPE=relwithdebinfo MKJOBS=4 ./launchBuildMain.sh

4.5 依赖升级操作

• Linux：运行include/scripts/build-Linux-sdk.sh，同版本已存在于SDK_HOME的库不会被重复构建；脚本通常以“包内某文件是否存在”判断是否需要构建，强制重编时先删除该探针文件。升级版本需将源码上传到downloads.natron.fr/Third_Party_Sources，在common.sh中更新包文件名；新增补丁放入include/patches/LIBRARY/并编辑 sdk 脚本。TAR_SDK=1可生成 SDK tarball，UPLOAD_SDK=1可一并上传。
• Windows：同上，对应脚本为include/scripts/build-Windows-sdk.sh。
• macOS：依赖由 MacPorts 管理，更新 Natron 专属包时修改Natron/tools/MacPorts下的Portfile即可。

五、buildmaster：供参考的旧版构建农场脚本

tools/buildmaster 目录存放的是 Natron 旧构建农场（build farm）时代使用的脚本，仅供参考——它们依赖一套复杂的基础设施（每种架构一台构建机、存放构建结果的数据库、存放二进制与符号的 Web 服务器等）。README 明确指出 jenkins 脚本更新，但两者都未曾用于产出正式 release。

主脚本为buildmaster.sh，启动方式：

• OS X 10.6、Linux CentOS 6.4 32 位、Linux CentOS 64 位：env NATRON_LICENSE=GPL ./buildmaster.sh
• Windows 7 64 位（并行构建 32/64 位版本）：

env NATRON_LICENSE=GPL MSYSTEM=MINGW32 BITS=32 MKJOBS=2 ./buildmaster.sh env NATRON_LICENSE=GPL MSYSTEM=MINGW64 BITS=64 MKJOBS=2 ./buildmaster.sh

构建 Windows 安装包的脚本位于buildmaster/include/scripts/build-Windows-installer.sh，每当依赖 DLL 文件名变化时必须更新（这一工作已在对应的 jenkins 脚本中自动化）。

六、docker：一键获得预置 SDK 的构建环境

tools/docker 提供构建预装 Natron SDK 的 Docker 镜像的工具。这些镜像基于 CentOS6 构建（可通过修改tools/jenkins/include/scripts/build-Linux-sdk.sh中的DOCKER_BASE更换基础镜像），以保证对绝大多数 Linux 发行版的兼容性。

6.1 拉取预构建镜像

docker pull natrongithub/natron-sdk # 64 位 docker pull natrongithub/natron-sdk-i386 # 32 位

6.2 启动一次构建

将本机目录绑定到容器内/home/builds_archive：

mkdir builds docker run -it --rm --mount src="$(pwd)/builds",target=/home/builds_archive,type=bind natrongithub/natron-sdk:latest

默认执行 snapshot 构建；可通过--env定制变量（完整清单见 tools/jenkins/launchBuildMain.sh 顶部注释），例如限制并行任务数：

docker run -it --rm --mount src="$(pwd)/builds",target=/home/builds_archive,type=bind --env MKJOBS=2 natrongithub/natron-sdk:latest

6.3 指定分支、提交或发布构建

# 构建 RB-2.4 分支快照 docker run -it --rm --mount src="$(pwd)/builds",target=/home/builds_archive,type=bind --env GIT_BRANCH=RB-2.4 natrongithub/natron-sdk:latest # 从个人 fork 构建 docker run -it --rm --mount src="$(pwd)/builds",target=/home/builds_archive,type=bind \ --env GIT_URL_IS_NATRON=1 --env GIT_URL=<fork 地址> --env GIT_BRANCH=my-feature-branch natrongithub/natron-sdk:latest # 发布构建（要求 Natron 仓库有 v2.4.1 标签、插件仓库有 Natron-2.4.1 标签） docker run -it --rm --env RELEASE_TAG=2.4.4 --env NATRON_BUILD_NUMBER=1 --env NATRON_DEV_STATUS=STABLE \ --mount src="$(pwd)/builds",target=/home/builds_archive,type=bind natrongithub/natron-sdk:latest

6.4 交互式调试

构建失败时可进入容器手动执行launchBuildMain.sh：

docker run -it --rm --mount src="$(pwd)/artifacts",target=/home/jenkins_artifacts,type=bind \ --mount src="$(pwd)/builds",target=/home/builds_archive,type=bind natrongithub/natron-sdk:latest bash

重新构建 SDK 镜像则使用tools/docker/natron-sdk/build.sh（64 位）与tools/docker/natron-sdk-i386/build.sh（32 位）。

七、MINGW-packages：MSYS2 平台专属软件包

tools/MINGW-packages 存放MSYS2 平台的 Natron 专属软件包，包括：

• 采用不同许可证的 ffmpeg 与 libraw 版本（如mingw-w64-ffmpeg-gpl2、mingw-w64-libraw-gpl2）；
• 打过补丁的 Qt4；
• OpenImageIO 1.7 版本（因更高版本在退出 Natron 时会挂起，对应 OpenImageIO 上游 issue #1795）；
• mingw-w64-x264-git、mingw-w64-osmesa、mingw-w64-natron-setup等额外包。

其中的check.sh脚本用于检查软件包是否需要更新，前提是../../../MINGW-packages处存在官方 MINGW-packages 仓库的 clone。README 特别注明mingw-w64-pyside-qt4与mingw-w64-shiboken-qt4因“一直可用”而长期未更新，属于有意为之。

八、license：许可证合规与依赖清单

tools/license 保存Natron 及其全部依赖（含插件依赖）的许可证文件。核心合规要求如下：

• Natron 主发行版采用GPL2，因此必须确保没有任何依赖是 GPL3；
• 若代码所有者允许，Natron 也可采用其他许可证（LGPL 或商业授权）分发，但此时GPL2 组件不可使用——例如只能使用 ffmpeg 与 libraw 的 LGPL 版本，且 poppler 不可使用。

这些许可证文件通过 Gui/GuiResources.qrc 打入资源，最终在 Natron 的 About 窗口中展示。组件级清单（Python、PySide、Qt、Boost、OpenImageIO、OpenColorIO、FFmpeg、SeExpr、Mesa、G'MIC 等数百个组件的许可证归属）详见 tools/license/components/README.md。

九、mkTarballs.sh：从发布标签制作源码包

tools/mkTarballs.sh 用于从发布标签生成Natron 与各插件仓库的源码 tarball。用法为./mkTarballs.sh x.y.z（形如2.4.1的版本号）。

脚本流程：在/tmp/Natron-sources-x.y.z下依次克隆 Natron 及其插件仓库（openfx-io、openfx-misc、openfx-gmic、openfx-arena）；Natron 仓库检出标签x.y.z，插件仓库检出Natron-x.y.z；随后git submodule update -i --recursive拉取子模块、删除各.git目录，最终打包为${仓库名}-${版本}.tar.xz。README 提示该脚本“可能需要更新或修复”。

十、normalize 与 uncrustify：代码风格维护工具链

10.1 normalize：Qt 信号/槽签名归一化

tools/normalize 是Qt4 的normalize工具源码，用于归一化 Natron 源码中SIGNAL()与SLOT()宏内的函数签名，可带来微小的运行时性能提升。多数代码格式化工具会破坏归一化后的签名，因此 normalize 应放在格式化工具之后运行。

10.2 uncrustify：格式化与修复的完整步骤

tools/uncrustify 提供 uncrustify.cfg 配置与 uncrustify-post.sed 修复脚本。uncrustify 同样会“破坏某些内容”，因此源码在运行后需要修复。完整流程：

# 1. 先运行 uncrustify uncrustify -c tools/uncrustify/uncrustify.cfg --replace */*.cpp */*.h # 2. 用提供的 sed 脚本修复 uncrustify 的输出 sed -f tools/uncrustify/uncrustify-post.sed -i .bak */*.cpp */*.h # 3. 运行 Qt 的 normalize 工具修复 signals/slots for d in Gui Engine App Global Renderer Tests; do tools/normalize/normalize --modify $d; done

十一、utils：零散维护脚本

tools/utils 收集若干杂项维护工具：

• fixpngs.sh：遍历源码树中所有 PNG 文件，用 ImageMagick 的convert -strip -define png:exclude-chunks=date去除日期元数据（实现可重现构建），随后用optipng -o 7做无损压缩；
• generate_glad.sh：通过 pip 安装的 glad 重新生成 OpenGL 扩展加载代码，以GL_ARB_vertex_buffer_object等六个扩展、OpenGL 2.0 compatibility profile 生成到 Global/gladDeb 与 Global/gladRel（对应 debug 与 release 两套生成器）；
• runPostShiboken.sh：运行 shiboken 生成 Python 绑定后，用于修复源文件的脚本（对应 INSTALL_MACOS.md 与 INSTALL_LINUX.md 中“Generating Python bindings”一节）。

十二、valgrind 与 travis：内存检查与早期 CI

tools/valgrind 提供 valgrind 内存检查的抑制文件（suppressions-Natron-CentOS7.txt），用于压制第三方库（如 Python 的PyObject_Free）产生的已知误报。此外，在jenkins/include/natron/与buildmaster/include/natron/下还分别存放了 Python 专用抑制文件valgrind-python*.supp。

tools/travis 提供 Travis CI 时代的构建辅助脚本（install_dependencies.sh负责在 Ubuntu/macOS 上通过 apt/brew 安装全部依赖，coverity_env.sh用于 Coverity 静态扫描环境变量），与仓库根目录隐藏的.travis.yml配合使用。

十三、补充：README 未列出的配套目录

除 tools/README.md 逐项说明的目录外，仓库中还实际存在两个配套目录，可视为该文档的自然延伸：

• tools/appimage：make-appimage.sh将已解压的免安装 Linux tarball 转换为 AppImage，包括生成natron.desktop桌面条目、x-natron.xmlMIME 注册（绑定*.ntp工程文件）、AppRun符号链接，并借助 appimagetool 产出最终 AppImage；
• tools/homebrew：Homebrew 备用配方（README 建议优先使用 MacPorts 而非 Homebrew 构建可移植二进制，Homebrew 仅用于调试），其中opencolorio@1.rb、python@2.rb、seexpr@2.rb对应 homebrew-core 中已被移除的历史版本，需拷贝到homebrew-core/Formula后以--build-from-source安装。

结语

Natron 的tools目录完整承载了其跨平台工程化能力：MacPorts 与 MINGW-packages 分别维护 macOS/Windows 的专属依赖，jenkins 与 buildmaster 提供两代构建流水线，docker 实现可复现的 SDK 构建环境，genStaticDocs.sh 打通“插件文档 → Markdown → RST → Sphinx HTML”的发布链路，而 normalize、uncrustify、utils 与 valgrind 则保障代码风格与质量。无论是打包发布、接入 CI 还是日常维护，tools/README.md 都是理解这些脚本协作关系的起点。

• 音视频
• 视频处理
• 图形学
• 桌面应用