OpenToonz Windows 构建全指南基于 Visual Studio 2019 与 Qt 5.15 的源码编译、运行部署与 32 位 srv 服务生成【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz导读本文以 OpenToonz 官方 Windows 构建文档为核心系统讲解在 Windows 平台上从源码编译 OpenToonz 的完整流程从 Visual Studio 2019 与 Qt 5.15 的环境准备、Git LFS 大文件拉取、CMake 工程生成、第三方库头文件配置到 64 位主程序构建、运行环境部署、可选 Canon 相机支持以及用于 mov 等 QuickTime 格式解码的 32 位srv文件夹生成与翻译文件编译。读完本文你将能够独立在 Windows 上构建出一套可运行的 OpenToonz 开发环境并理解构建系统toonz/sources/CMakeLists.txt中各个选项与路径的真实含义。一、构建环境与版本前提根据官方文档 doc/how_to_build_win_ja.md 的说明Windows 版 OpenToonz 已确认可在Visual Studio 20192015 及以上亦可与Qt 5.15的组合下完成构建。这是本项目在 Windows 上的标准构建基线后续所有步骤均以此为前提。需要的软件如下软件用途说明Visual Studio Community 2019C 编译器与 IDE安装时勾选「使用 C 的桌面开发」工作负载CMake生成 Visual Studio 工程文件从 https://cmake.org/download/ 获取从源码结构看顶层构建脚本 toonz/sources/CMakeLists.txt 会依据编译器环境自动区分构建环境在 Windows 下走BUILD_ENV_MSVC分支toonz/sources/CMakeLists.txt#L44-L49并要求 C17 标准toonz/sources/CMakeLists.txt#L6-L7这正是 VS2019 所默认支持的标准与官方文档的版本要求相互印证。二、获取源码与 Git 行尾转换UTF-8 无 BOM 的坑首先将本仓库克隆到本地git clone 仓库地址文档中以$opentoonz表示本仓库的根目录下文沿用这一约定。为什么必须处理换行符CRLF官方文档特别提醒Visual Studio 无法正确识别不带 BOM 的 UTF-8 源码。当源码文件的换行符为 LF、且单行注释//以日文或其他多字节字符结尾时编译器会忽略换行导致下一行也被当作注释处理引发难以排查的编译错误。解决办法是在克隆前对 Git 做如下配置让 Git 在检出时将换行符转换为 CRLFgit config core.safecrlf truecore.safecrlf会在文件「LF ↔ CRLF」往返转换不一致时发出警告避免数据被意外改写。三、大型依赖库的安装体积较大的库并未包含在仓库内需要单独安装。仓库内thirdparty/目录下保留了 glut、glew、libmypaint 等小型库的源码与预编译产物如 thirdparty/glut/3.7.6/lib、thirdparty/glew/glew-1.9.0/bin而 Qt、OpenCV、boost 等大型依赖则需要你手动准备。1. Git LFS拉取lib与dll文件lib与dll文件由 Git Large File Storage 管理。请先安装 LFS 客户端然后在git clone之后执行git lfs pull该命令会把仓库中 LFS 指针指向的实际二进制文件如各第三方库的.lib/.dll下载到本地。2. Qt 5.1564 位版Qt 是 OpenToonz 的跨平台 GUI 框架。从 Qt 官网https://www.qt.io/download-open-source/下载 Qt Online InstallerQt Online Installer for Windows将Qt 5.1564 位版安装到任意目录。构建系统对 Qt 的定位有硬性检查。在 MSVC 环境下toonz/sources/CMakeLists.txt#L170-L176 的逻辑是若未显式指定QT_PATH默认尝试C:/Qt/5.15.2/msvc2019_6464 位构建变量为msvc2019${PLATFORM2}若该路径不存在则直接以FATAL_ERROR中止并提示QT_PATH not found: ${QT_PATH}. Specify QT_PATH properly.——这就是文档中提到的Specify QT_PATH properly错误的来源。随后构建系统要求找到的 Qt 模块包括 Core、Gui、Network、OpenGL、Svg、Xml、Script、Widgets、PrintSupport、LinguistTools、Multimedia、MultimediaWidgets、SerialPort、UiTools 等toonz/sources/CMakeLists.txt#L284-L299并校验最低版本 Qt 5.5.0toonz/sources/CMakeLists.txt#L306-L311。3. WinTab 支持的定制版 Qt 5.15.2可选但推荐官方文档指出Qt 从 5.12 起原生改用 Windows Ink API 处理数位板输入而 5.9 及之前使用的 WinTab API 与之行为不同已有多起由此引发的数位板兼容性问题报告。为此项目维护者分发了一款将官方在 Qt 6.0 才引入的「切换回 WinTab API」功能 cherry-pick 到 5.15.2 的定制版 Qt。该定制版提供了面向 MSVC2019-x64 的预编译包发布页为 https://github.com/shun-iwasawa/qt5/releases/tag/v5.15.2_wintab。使用该 Qt 后还需在 CMake 中启用WITH_WINTABON从源码看WITH_WINTAB选项定义于 toonz/sources/CMakeLists.txt#L110且只有在Windows 目标 64 位平台时才会真正生效位于 toonz/sources/toonz/CMakeLists.txt#L503-L505 的代码if (WITH_WINTAB AND BUILD_TARGET_WIN AND (PLATFORM EQUAL 64))才会追加-DWITH_WINTAB宏定义。该宏在源码中的实际消费点包括数位板初始化逻辑toonz/sources/toonz/main.cpp#L732-L734与偏好设置项toonz/sources/toonzlib/preferences.cpp#L701、toonz/sources/include/toonz/preferencesitemids.h#L215后者表示该设置项仅在定义了WITH_WINTAB时才会显示。4. OpenCVv4.1.0 及以上从 https://opencv.org/ 获取 OpenCVv4.1.0 或更高版本。构建时通过以下两种方式之一告诉 CMake OpenCV 的位置在 CMake GUI 中设置OpenCV_DIR变量设置环境变量OpenCV_DIR。OpenCV_DIR的值应指向 OpenCV 安装目录下的build文件夹例如C:/opencv/build。源码层面64 位平台在 Windows 上执行find_package(OpenCV 4.1 REQUIRED)toonz/sources/CMakeLists.txt#L331即版本下限被硬编码为 4.1若找不到会直接报错。OpenCV 会作为EXTRA_LIBS的一部分链接进OpenToonz主程序toonz/sources/toonz/CMakeLists.txt#L529。5. Boost从 http://www.boost.org/users/history/version_1_73_0.html 下载boost_1_73_0.zip解压后将该文件夹复制到$opentoonz/thirdparty/boost。文档原文此处写作「将boost_1_61_0复制到$opentoonz/thirdparty/boost」结合上下文「下载 boost_1_73_0.zip」应理解为解压后的 boost 目录原文疑似笔误。从构建脚本看toonz/sources/CMakeLists.txt#L596-L605 实际会按boost_1_89_0、boost_1_87_0、boost_1_86_0、boost_1_85_0、boost_1_75_0、boost_1_74_0、boost_1_73_0、boost_1_72_0等多个版本目录名在thirdparty下搜索并最终要求find_package(Boost 1.55 REQUIRED)。四、使用 CMake 生成 Visual Studio 工程启动 CMake GUI按以下步骤配置Where is the source code填写$opentoonz/toonz/sourcesWhere to build the binaries填写$opentoonz/toonz/build也可以放在其他位置若放在检出目录内建议以build开头命名——仓库的 .gitignore 第 11 行的build*规则会将其忽略避免污染 Git 工作区若更改了构建输出目录请相应替换下文中的路径。点击Configure选择生成器Visual Studio 16 2019 Win64若 Qt 未安装在默认位置会报错Specify QT_PATH properly此时将QT_PATH设为 Qt5 的实际安装路径例如C:/Qt/5.15.2/msvc2019_64即上文源码中默认尝试的路径点击Generate生成完毕后如果之后修改了CMakeLists.txt构建时 CMake 会自动重新运行无需再手动打开 CMake GUI。值得留意的是MSVC 分支会把所有运行时产物exe 与 dll统一输出到构建根目录CMAKE_RUNTIME_OUTPUT_DIRECTORY被设为${CMAKE_BINARY_DIR}见 toonz/sources/CMakeLists.txt#L625-L628这正是下文「$opentoonz/toonz/build/Release中生成文件」的原因。五、第三方库头文件配置VC 专用由于 Visual C 与 Unix 环境的配置宏不同构建前需要复制以下 4 个头文件均为「VC 专用配置」覆盖「默认配置」$opentoonz/thirdparty/LibJPEG/jpeg-9/jconfig.vc → $opentoonz/thirdparty/LibJPEG/jpeg-9/jconfig.h $opentoonz/thirdparty/tiff-4.0.3/libtiff/tif_config.vc.h → $opentoonz/thirdparty/tiff-4.0.3/libtiff/tif_config.h $opentoonz/thirdparty/tiff-4.0.3/libtiff/tiffconf.vc.h → $opentoonz/thirdparty/tiff-4.0.3/libtiff/tiffconf.h $opentoonz/thirdparty/libpng-1.6.21/scripts/pnglibconf.h.prebuilt → $opentoonz/thirdparty/libpng-1.6.21/pnglibconf.h其中 jpeg 库在仓库中对应目录为 thirdparty/libjpeg-turbo预编译头文件位于 thirdparty/libjpeg-turbo/includetiff、libpng 的源码与预编译库分别位于 thirdparty/tiff-4.0.3 与 thirdparty/libpng-1.6.21。补充当前版本的 CMake 脚本toonz/sources/CMakeLists.txt#L153-L166在 MSVC 环境下也会在 Configure 阶段自动完成 tiff 与 libpng 这三个头文件的复制pnglibconf.h.prebuilt、tif_config.vc.h、tiffconf.vc.h即「配置第三方库」一步在较新版本中已被 CMake 接管。若你使用的版本仍要求手动复制按上表执行即可。六、64 位版主程序构建打开$opentoonz/toonz/build/OpenToonz.sln选择Release配置执行构建构建产物生成于$opentoonz/toonz/build/Release由于上一节提到的输出目录设置exe 与各 dlltnzcore、tnzbase、toonzlib、image 等会被放在同一目录下方便直接部署运行。七、可选启用 Canon 数码相机支持若需要在 OpenToonz 中直接控制 Canon 数码相机停格动画工作流常用需要额外准备Canon EOS Digital SDKEDSDK获取方式参见佳能官网的开发者 API 页面。然后在 CMake 中启用WITH_CANONON从源码看WITH_CANON选项定义于 toonz/sources/CMakeLists.txt#L108默认 OFF。启用后主程序会追加-DWITH_CANON宏toonz/sources/toonz/CMakeLists.txt#L499-L50164 位构建会引入EDSDK.lib并链接 EDSDKtoonz/sources/CMakeLists.txt#L400-L404、toonz/sources/toonz/CMakeLists.txt#L530-L532宏的消费集中在停格动画模块 toonz/sources/stopmotion如 toonz/sources/stopmotion/canon.cpp、toonz/sources/stopmotion/stopmotioncontroller.cpp以及相机菜单项toonz/sources/toonz/sceneviewer.cpp#L1745、toonz/sources/toonz/mainwindow.cpp#L3603。运行时将 Canon EDSDK 的.dll文件复制到OpenToonz.exe所在的同一文件夹。八、运行环境部署构建完成后需要把可执行文件与依赖库组装成一个可运行的发布目录将$opentoonz/toonz/build/Release中的内容复制到任意发布文件夹以OpenToonz.exe的路径为参数运行 Qt 自带的windeployqt.exewindeployqt.exe 发布文件夹/OpenToonz.exe该命令会把运行所需的 Qt 库Core、Gui、Widgets 等自动收集到OpenToonz.exe同目录再将以下文件复制到OpenToonz.exe同目录$opentoonz/thirdparty/glut/3.7.6/lib/glut64.dll$opentoonz/thirdparty/glew/glew-1.9.0/bin/64bit/glew32.dll$opentoonz/thirdparty/libmypaint/dist/64/*.dll即 thirdparty/libmypaint/dist/64 下的全部 dll如 libmypaint-1-4-0.dll、libiconv-2.dll 等OpenCV、libjpeg-turbo 的.dll文件将二进制版 OpenToonz 安装目录中的srv文件夹复制到OpenToonz.exe同目录没有srvOpenToonz 也能运行但无法处理 mov 等 QuickTime 格式srv内文件的生成方法见后文「十」。上述 dll 路径均已在仓库中确认存在glut64.dll 位于 thirdparty/glut/3.7.6/libglew32.dll 位于 thirdparty/glew/glew-1.9.0/bin/64bit。九、Stuff 文件夹与注册表键如果机器上已经安装过二进制版 OpenToonz下述两步Stuff 复制与注册表键通常已自动完成可跳过。复制 Stuff 文件夹将$opentoonz/stuff复制到任意位置创建注册表键在注册表编辑器中创建如下键并把值设为上一步中 stuff 文件夹的路径HKEY_LOCAL_MACHINE\SOFTWARE\OpenToonz\OpenToonz\TOONZROOTOpenToonz 通过该注册表键定位素材库画笔、样式、着色板、布局等见 stuff/config 与 stuff/library等运行资源。完成后直接运行OpenToonz.exe能正常启动即代表构建成功。十、srv文件夹内文件的生成32 位构建 QuickTime SDK为什么需要 32 位进程OpenToonz 使用 QuickTime SDK 支持 mov 等格式而QuickTime SDK 只有 32 位版本。因此项目将 QuickTime SDK 内嵌进一个名为t32bitsrv.exe的 32 位辅助进程64 位版 OpenToonz 通过它间接调用 QuickTime 功能。从源码看t32bitsrv是独立的小型可执行目标toonz/sources/t32bitsrv/CMakeLists.txt依赖Qt5::Core、Qt5::Network、tnzcore、image且顶层 CMake 只在32 位平台 MSVC/Apple条件下才加入该子目录toonz/sources/CMakeLists.txt#L763-L765。同时32 位构建会链接 QuickTime 的QTMLClient.libtoonz/sources/CMakeLists.txt#L394-L396。以下步骤在生成srv内容的同时也会构建出一个 32 位版 OpenToonz。1. 安装 32 位版 Qt使用与 64 位版相同的 Qt 安装器额外安装Qt 5.x32 位版到任意目录例如C:/Qt/5.15.2/msvc2019。2. 获取 QuickTime SDK注册 Apple 开发者账号后从 Apple 下载页面搜索下载QuickTime 7.3 SDK for Windows.zip安装 QuickTime SDK将C:\Program Files (x86)\QuickTime SDK中的内容复制到$opentoonz/thirdparty/quicktime/QT73SDK仓库中该目录当前为空的占位见 thirdparty/quicktime/QT73SDK 与 thirdparty/quicktime/copy_QT73SDK.txt需自行填充 SDK 文件。3. 生成 32 位 Visual Studio 工程步骤与 64 位版相同仅替换以下参数构建目录$opentoonz/toonz/build→$opentoonz/toonz/build32生成器Visual Studio 16 2019x64→ Visual Studio 16 2019Win32QT_PATH指向 32 位版 Qt 的安装路径4. 构建 32 位版打开并构建$opentoonz/toonz/build32/OpenToonz.sln5. 组装srv文件夹在 64 位版的srv文件夹中放入以下文件来源文件$opentoonz/toonz/build32/Releaset32bitsrv.exe、image.dll、tnzbase.dll、tnzcore.dll、tnzext.dll、toonzlib.dll32 位 Qt 安装目录运行windeployqt.exe得到的所需库另追加Qt5Gui.dll$opentoonz/thirdparty/glut/3.7.6/libglut32.dll十一、翻译文件.ts / .qm的生成OpenToonz 的界面翻译遵循 Qt 标准流程从源码提取可翻译文本生成.ts文件对.ts文件进行人工翻译由.ts编译生成.qm文件运行时实际加载的格式。在 Visual Studio 解决方案中存在多个以translation_开头的工程如translation_toonz、translation_toonzqt、translation_tnztools等。只构建translation_???工程在解决方案资源管理器中右键选择「仅生成…」即可一次性生成.ts与.qm文件。这些工程被标记为不参与解决方案的整体构建EXCLUDE_FROM_DEFAULT_BUILD TRUE因此正常 Build 不会触发翻译流程。从源码看翻译工程由add_translation()函数动态生成toonz/sources/CMakeLists.txt#L679-L695为每个模块创建translate_update_${module}自定义目标支持的语言代码列表定义于 toonz/sources/CMakeLists.txt#L662-L664japanese、italian、french、spanish、chinese、german、russian、korean、czech、portuguese_brazil对应的.ts源文件按语言分目录存放于 toonz/sources/translations。随后add_compile_translations_command()toonz/sources/CMakeLists.txt#L700-L729会在主工程构建后自动调用lrelease把.ts编译为.qm并输出到stuff/config/loc/语言显示名/目录供运行时加载。十二、常见问题与排错提示Specify QT_PATH properly错误说明 Qt 未安装到默认路径。默认路径在 MSVC 下为C:/Qt/5.15.2/msvc2019_6464 位与C:/Qt/5.15.2/msvc201932 位请在 CMake 中显式设置QT_PATH指向实际安装目录。OpenCV 找不到确认版本 ≥ 4.1.0并确保OpenCV_DIR指向 OpenCV 安装目录下的build文件夹。jconfig.h/tif_config.h/tiffconf.h/pnglibconf.h缺失按「五、第三方库头文件配置」复制对应的.vc或.prebuilt版本新版 CMake 也会在 Configure 阶段自动处理。mov 文件无法导入/导出srv文件夹缺失或未正确放置需要按「十、srv 文件夹生成」完成 32 位构建并部署。日文注释导致的诡异编译错误确认core.safecrlf true已配置且源码以 CRLF 检出规避 MSVC 对无 BOM UTF-8 的解析问题。数位板行为异常若使用 Qt ≥ 5.12 的 Windows Ink 行为与预期不符可换用 WinTab 定制版 Qt 5.15.2并在 CMake 中启用WITH_WINTABON仅 64 位构建生效。至此从环境准备、依赖安装、CMake 配置、双平台64 位主程序 32 位srv构建到运行部署与翻译编译Windows 上 OpenToonz 的完整构建链路已全部打通。【免费下载链接】opentoonzOpenToonz - An open-source full-featured 2D animation creation software项目地址: https://gitcode.com/GitHub_Trending/op/opentoonz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考