KLayout macOS 源码构建完全指南：build4mac.py 从模块组合、编译部署到 QA 测试与 DMG 打包

• 硬件开发
• 桌面应用
• 图形学

本文以 KLayout 仓库中macbuild目录的官方构建说明 macbuild/ReadMe.md 为主体，完整覆盖 KLayout 0.30.9+ 在 macOS 上的源码构建全流程：如何选择 Qt5/Qt6 与 Ruby/Python 模块组合、如何调用build4mac.py完成编译与部署、如何用macQAT.py运行ut_runner单元 QA 测试、以及如何用makeDMG4mac.py制作可分发的 DMG 安装包。读完本文，你能够在一台 Intel x86_64 或 Apple Silicon 的 Mac 上独立复现 KLayout 的 macOS 原生构建，并理解输出包目录命名（ST-/LW-/HW-/EX-）背后的源码级逻辑。

1. 适用系统与构建目标

macbuild目录包含构建 KLayout（适用版本 0.30.9 及以上）所需的全部 macOS 构建文件。根据 macbuild/ReadMe.md 的说明，当前支持的 macOS 版本为：

对更早的操作系统（Ventura 13.7.8、Monterey 12.7.6、Big Sur 11.7.10、Catalina 10.15.7、Mojave 10.14、High Sierra 10.13、Sierra 10.12、El Capitan 10.11）的构建支持已经停止，也不再提供预构建的 DMG 包。原文档说明这些旧系统中 Ventura 与 Monterey 上"构建理论上仍可能成功"，但已不属于官方维护范围。这一点可以从源码得到印证：macbuild/build4mac.py 中的Get_Default_Config()通过platform.uname()解析 OS 主版本号并映射为平台名（27→GoldenGate、25→Tahoe、24→Sequoia、23→Sonoma、22→Ventura、21→Monterey），而对非Darwin系统或未列出的发行版会直接打印错误并sys.exit(1)。

需要特别注意的架构限制：从源码结构看，macbuild/build4mac.py 要求机器为x86_64；若检测到arm64（Apple Silicon）且平台在支持列表中，则会设置环境变量QMAKE_APPLE_DEVICE_ARCHS=arm64以构建原生 ARM64 版本。原文档指出，其主线目标机器是Intel x86_64 + macOS Sequoia，Apple Silicon 环境的详细构建流程虽然"与 Intel Mac 基本相同"，但文档未单独展开。

2. Qt 框架的选择

KLayout 的 macOS 构建依赖 Qt 图形框架。原文档给出的三种来源：

• 默认：MacPorts 的 Qt5，通常位于/opt/local/libexec/qt5/；
• Homebrew 的 Qt6，通常位于/usr/local/opt/qt@6/（Apple Silicon 上为/opt/homebrew/opt/qt@6/）；
• Anaconda3 的 Qt6，安装配置稍复杂（见第 7 节 6F 用例）。

macbuild/build4mac_env.py 是这些模块路径的集中定义文件。它为每个 Qt 来源定义了qmake、macdeployqt与libdir三个关键路径，例如：

Qt5MacPorts = { 'qmake' : '/opt/local/libexec/qt5/bin/qmake', 'deploy': '/opt/local/libexec/qt5/bin/macdeployqt', 'libdir': '/opt/local/libexec/qt5/lib' } Qt6Brew = { 'qmake' : '%s/opt/qt@6/bin/qmake' % DefaultHomebrewRoot, 'deploy': '%s/opt/qt@6/bin/macdeployqt' % DefaultHomebrewRoot, 'libdir': '%s/opt/qt@6/lib' % DefaultHomebrewRoot }

其中 Homebrew 根目录按架构自动区分：x86_64机器取/usr/local，arm64机器取/opt/homebrew（见 macbuild/build4mac_env.py）。对于 Anaconda3，Qt5/Qt6 分别安装在虚拟环境klayout-qt5/klayout-qt6下（x86_64 位于/Applications/anaconda3/envs/，arm64 位于/opt/anaconda3/envs/），Qt6 环境使用qmake6与macdeployqt6可执行文件。

原文档还给出两点重要提示：

1. Qt6 迁移仍在进行中，可用但可能遇到构建或运行时错误；
2. 构建 KLayout >= 0.29.0 且使用 Homebrew 环境时，必须使用 Qt6（>= 6.7.0），以解决上游报告的一个 Qt5 编译问题（原文档引用了上游 issue #1599）。

3. 脚本语言支持：Ruby 与 Python 的模块组合

KLayout 支持 Ruby 与 Python 两种对象脚本语言，构建时通过build4mac.py的组合参数决定绑定哪种语言、以及语言解释器来自哪个软件包管理器。macbuild/build4mac_env.py 按以下维度组织字典：

• Ruby：nil（不绑定）/Sys（各 macOS 版本系统自带的 Ruby 2.6，解释器位于/System/Library/Frameworks/Ruby.framework/Versions/2.6/usr/bin/ruby，头文件与libruby.tbd取自 Xcode SDK 或 Command Line Tools SDK）/MP34（MacPorts Ruby 3.4，/opt/local/bin/ruby3.4）/HB34（Homebrew Ruby 3.4，{Homebrew 根}/opt/ruby@3.4）/Ana3（Anaconda3 环境内的 Ruby 3.4）；
• Python：nil/Sys（系统 Command Line Tools 自带的 Python 3.9，框架位于/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/）/MP314、MP313（MacPorts Python 3.14/3.13，位于/opt/local/Library/Frameworks/Python.framework/）/HB314、HB313、HB311（Homebrew 对应版本）/HBAuto（自动探测 Homebrew 中最新的 Python 3.x）/Ana3（Anaconda3 环境内 Python）。

其中HBAuto的实现值得注意：macbuild/build4mac_env.py 用正则扫描{Homebrew 根}/opt/python*/Frameworks/Python.framework，按版本号排序取最大者；若系统完全没有 Homebrew Python，会打印 WARNING 并禁用该选项。

每个模块字典统一包含exe（解释器）、inc（头文件目录）、lib（动态库）三项，供后续 qmake/make 阶段生成正确的编译链接参数。

4. 构建前置条件

按照原文档第 4 节，构建前需要准备：

• 与目标 macOS 匹配的最新 Xcode 与 Command Line Tools；
• MacPorts 的 Qt5，或 Homebrew / Anaconda3 的 Qt6；
• 来自 MacPorts、Homebrew 或 Anaconda3 的libgit2；
• 可选：MacPorts、Homebrew 或 Anaconda3 的 Ruby 与 Python 包。

对于 Ruby/Python 的具体版本匹配要求，原文档要求参考 macbuild/build4mac_env.py 中各字典项注释里列出的安装命令（如sudo port install ruby34、brew install python@3.14、conda install -y --override-channels -c conda-forge "ruby=3.4.7"等）。

5. build4mac.py 命令行选项详解

macbuild/build4mac.py 是 macOS 构建的顶层 Python 脚本，操作系统类型会被自动检测（-q选项的默认值按平台生成，GoldenGate/Tahoe/Sequoia/Sonoma 上默认组合为qt5macports+sys+sys）。完整选项表如下（继承自原文档第 5 节）：

<< Usage of 'build4mac.py' >> for building KLayout 0.30.9 or later on different Apple macOS platforms. $ [python] ./build4mac.py option & argument : descriptions (refer to 'macbuild/build4mac_env.py' for details) | default value ----------------------------------------------------------------------------------------+--------------- [-q|--qt <type>] : case-insensitive type=['Qt5MacPorts', 'Qt5Brew', 'Qt5Ana3', | qt5macports : 'Qt6MacPorts', 'Qt6Brew', 'Qt6Ana3''] | : Qt5MacPorts: use Qt5 from MacPorts | : Qt5Brew: use Qt5 from Homebrew | : Qt5Ana3: use Qt5 from Anaconda3 | : Qt6MacPorts: use Qt6 from MacPorts (*) | : Qt6Brew: use Qt6 from Homebrew (*) | : Qt6Ana3: use Qt6 from Anaconda3 (*) | : (*) migration to Qt6 is ongoing | [-r|--ruby <type>] : case-insensitive type=['nil', 'Sys', 'MP34', 'HB34', 'Ana3'] | sys : nil: don't bind Ruby | : Sys: use [GoldenGate|Tahoe|Sequoia|Sonoma]-bundled Ruby 2.6 | : MP34: use Ruby 3.4 from MacPorts | : HB34: use Ruby 3.4 from Homebrew | : Ana3: use Ruby 3.4 from Anaconda3 | [-p|--python <type>] : case-insensitive type=['nil', 'Sys', 'MP314', 'HB314', 'Ana3', | sys : 'MP313', 'HB313', | : 'HB311', 'HBAuto'] | : nil: don't bind Python | : Sys: use [GoldenGate|Tahoe|Sequoia|Sonoma]-bundled Python 3.9 | : MP314: use Python 3.14 from MacPorts | : HB314: use Python 3.14 from Homebrew | : Ana3: use Python 3.14 from Anaconda3 | : MP313: use Python 3.13 from MacPorts | : HB313: use Python 3.13 from Homebrew | : HB311: use Python 3.11 from Homebrew (+) | : (+) required to provide the legacy pip in HW-*.dmg | : HBAuto: use the latest Python 3.x auto-detected from Homebrew | [-P|--buildPymod] : build and deploy Pymod (*.whl) for LW-*.dmg | disabled [-n|--noqtbinding] : don't create Qt bindings for ruby scripts | disabled [-u|--noqtuitools] : don't include uitools in Qt binding | disabled [-s|--no32bitcoord] : don't use short (32bit) coordinates; use long (64bit) instead | disabled [-g|--nolibgit2] : don't include libgit2 for Git package support | disabled [-m|--make <option>] : option passed to 'make' | '--jobs=4' [-d|--debug] : enable debug mode build; AddressSanitizer (ASAN) is linked | disabled [-c|--checkcom] : check command-line and exit without building | disabled [-y|--deploy] : deploy executables and dylibs, including Qt's Frameworks | disabled [-Y|--DEPLOY] : deploy executables and dylibs for those who built KLayout | disabled : from the source code and use the tools in the same machine | : ! After confirmation of the successful build of 'klayout.app', | : rerun this script with BOTH: | : 1) the same options used for building AND | : 2) <-y|--deploy> OR <-Y|--DEPLOY> | : optionally with [-v|--verbose <0-3>] | [-v|--verbose <0-3>] : verbose level of `macdeployqt' (effective with -y only) | 1 : 0 = no output, 1 = error/warning (default), | : 2 = normal, 3 = debug | [-?|--?] : print this usage and exit; in zsh, quote like '-?' or '--?' | disabled

结合源码可以补充几点文档未展开的实现细节：

• 选项解析：-q/-r/-p的值经大写化后在候选字典中查找（大小写不敏感），非法取值会打印错误并终止（见 macbuild/build4mac.py）。
• -y与-Y互斥：两者同时传入会报错退出；-y（full deploy）会内嵌 Qt（及视组合内嵌 Python）Framework，-Y（partial deploy）只部署可执行文件与 dylib，不内嵌 Qt[5|6]/Ruby/Python，因此适用于"在本机源码构建、本机直接使用"的场景。
• 版本号来源：KLayout 版本从项目根目录的version.sh读取（见 macbuild/build4mac.py 的GetKLayoutVersionFrom("./version.sh")），最终参与包目录命名。
• -m选项默认--jobs=4，直接透传给make；-d开启 debug 模式并链接 AddressSanitizer。

输出包目录命名规则（源码级解释）

构建/部署完成后，产物位于一个形如ST-qt5MP.pkg.macos-Sequoia-C32-release-RsysPsys的目录。目录名由 macbuild/build4mac.py 按模板%s%s.pkg.macos-%s-%s-%s-%s % (PackagePrefix, qt, Platform, coordSize, mode, ruby_python)生成，各段含义：

从源码结构看，前缀的判定逻辑集中在 macbuild/build4mac.py：-Y一律LW-；-y时若 Ruby 与 Python 均为系统自带则为ST-（EmbedQt=True），若 Python 为 Homebrew 3.11（或 HBAuto 恰好解析到 3.11）则为HW-（EmbedQt=True、EmbedPython3=True），其余为EX-；且HW-包要求 Qt 来自 MacPorts 或 Homebrew（Anaconda3 的 Qt 不允许内嵌），不满足时直接退出。

6. 实战用例（6A～6H）

以下各用例中的实际文件名取自 macOS Sequoia 环境；在不同 macOS 上，平台名等片段会相应变化。所有构建用例的共同流程为：*安装依赖 → 调用build4mac.py构建（约一小时）→ 用相同构建参数加-y/-Y重新运行以部署klayout.app内的可执行文件与 dylib（buddy 命令行工具 strm一并部署到klayout.app/Contents/Buddy/）→ 将klayout.app拷贝到/Applications**。

6A. 标准构建：系统自带 Ruby/Python + MacPorts Qt5

0. 安装 MacPorts 后安装 Qt5 与 libgit2：

$ sudo port install coreutils $ sudo port install findutils $ sudo port install qt5 $ sudo port install libgit2

确认系统自带 Python 存在：

/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/*

原文档说明，撰写时该 Python 版本为3.9.6（与源码字典PythonSequoia指向的Python3.framework/Versions/3.9一致）。

1. 调用构建脚本（这些选项在 Tahoe/Sequoia/Sonoma 上即默认值）：

$ cd /where/'build.sh'/exists $ ./build4mac.py -q qt5macports -r sys -p sys

2. 确认构建成功（约一小时，取决于机器配置）。
3. 用相同选项加-y重新运行，将可执行文件与库部署到klayout.app内：

$ ./build4mac.py -q qt5macports -r sys -p sys -y

产物位于ST-qt5MP.pkg.macos-Sequoia-C32-release-RsysPsys目录（ST-=标准包；qt5MP=MacPorts Qt5；C32=32 位坐标；RsysPsys=系统 Ruby 2.6 + 系统 Python 3.9）。 4. 将生成的klayout.app拷贝/移动到/Applications完成安装。

6B. 全 MacPorts 构建：MacPorts Ruby 3.4 + MacPorts Python 3.14

0. 安装依赖：

$ sudo port install coreutils $ sudo port install findutils $ sudo port install qt5 $ sudo port install ruby34 $ sudo port install python314 $ sudo port install py314-pip $ sudo port install libgit2

1. 构建：

$ cd /where/'build.sh'/exists $ ./build4mac.py -q qt5macports -r mp34 -p mp314

2. 确认构建成功。
3. 相同选项加-Y重新运行以部署：

$ ./build4mac.py -q qt5macports -r mp34 -p mp314 -Y

若在步骤 1 与步骤 3 都使用--buildPymod选项，KLayout 独立 Python 包（*.whl）将被构建并部署到klayout.app/Contents/pymod-dist/。

产物位于LW-qt5MP.pkg.macos-Sequoia-C32-release-Rmp34Pmp314目录（LW-=轻量包；Rmp34Pmp314=MacPorts Ruby 3.4 + MacPorts Python 3.14）。 4. 将klayout.app安装到/Applications。

6C. 全 Homebrew 构建：Homebrew Ruby 3.4 + Homebrew Python 3.14

注意：构建 KLayout >= 0.29.0 需要 Qt6 >= 6.7.0，以解决上游 Qt5 编译问题（issue #1599）。

0. 安装依赖，并运行 Homebrew Python 目录结构整理工具 macbuild/python3HB.py（该工具在{Homebrew 根}/opt/python@<ver>/lib/下建立Python.framework -> ../Frameworks/Python.framework/的标准化符号链接结构，支持-v 3.11/3.12/3.13/3.14）：

$ brew install qt@6 $ brew install ruby@3.4 $ brew install python@3.14 $ brew install libgit2 $ cd /where/'build.sh'/exists $ cd macbuild $ ./python3HB.py -v 3.14

1. 构建：

$ cd /where/'build.sh'/exists $ ./build4mac.py -q qt6brew -r hb34 -p hb314

2. 确认构建成功。
3. 相同选项加-Y部署：

$ ./build4mac.py -q qt6brew -r hb34 -p hb314 -Y

产物位于LW-qt6Brew.pkg.macos-Sequoia-C32-release-Rhb34Phb314目录。 4. 将klayout.app安装到/Applications。

警告：Homebrew Python >= 3.12 不再提供传统pip命令，直接使用会报error: externally-managed-environment。按照 Homebrew 的建议应使用虚拟环境，详见Resources/script-bundle-B.zip内的HomebrewUser-ReadMeFirst.txt。

6D. 部分 Homebrew 构建：系统 Ruby + Homebrew Python 3.11

注意：构建 KLayout >= 0.29.0 需要 Qt6 >= 6.7.0（同 6C 的原因）。

0. 安装依赖：

$ brew install qt@6 $ brew install python@3.11 $ brew install libgit2 $ cd /where/'build.sh'/exists $ cd macbuild $ ./python3HB.py -v 3.11

1. 构建：

$ cd /where/'build.sh'/exists $ ./build4mac.py -q qt6brew -r sys -p hb311

2. 确认构建成功。
3. 相同选项加-y重新运行，将可执行文件与库（含 Qt 与 Python 两套 Frameworks）部署到klayout.app内，strm* 工具同样部署到klayout.app/Contents/Buddy/：

$ ./build4mac.py -q qt6brew -r sys -p hb311 -y

产物位于HW-qt6Brew.pkg.macos-Sequoia-C32-release-RsysPhb311目录（HW-=重量包，因同时内嵌 Qt6 与 Python Frameworks；RsysPhb311=系统 Ruby + Homebrew Python 3.11）。 4. 将klayout.app安装到/Applications。

重要：目前尚不支持部署 Homebrew Ruby。因此若计划使用-y选项进行完整部署，构建时必须使用-r sys。

6E. 异构组合：MacPorts Qt5 + 系统 Ruby + Homebrew Python 3.11

注意：这是构建常用 HW*.dmg 包的另一种实用方案。

0. 分别安装两套依赖：

# MacPorts 侧 $ sudo port install coreutils $ sudo port install findutils $ sudo port install qt5 $ sudo port install libgit2 # Homebrew 侧 $ brew install python@3.11 $ cd /where/'build.sh'/exists $ cd macbuild $ ./python3HB.py -v 3.11

1. 构建：

$ cd /where/'build.sh'/exists $ ./build4mac.py -q qt5macports -r sys -p hb311

2. 确认构建成功。
3. 相同选项加-y部署：

$ ./build4mac.py -q qt5macports -r sys -p hb311 -y

产物位于HW-qt5MP.pkg.macos-Sequoia-C32-release-RsysPhb311目录（HW-=重量包，内嵌 Qt5 与 Python Frameworks）。 4. 将klayout.app安装到/Applications。

6F. 全 Anaconda3 构建：Anaconda3 Ruby 3.4 + Anaconda3 Python 3.13

若 Anaconda3 安装在$HOME/opt/anaconda3/（或其他位置），需先建立符号链接/Applications/anaconda3/ -> $HOME/opt/anaconda3/，然后按下述步骤安装（以 Intel x86_64 的Anaconda3-2025.06-0-MacOSX-x86_64.pkg为例，装到/Applications后创建新虚拟环境）：

1) Create a new env "klayout-qt6" (with stable solver & channels) switch solver to libmamba for faster/more stable resolves $ conda install -n base -y conda-libmamba-solver $ conda config --set solver libmamba Create the environment (on this x86_64 machine it will pull osx-64 builds) $ conda create -n klayout-qt6 python=3.13 -y $ conda activate klayout-qt6 In this env only, prefer conda-forge strictly (to avoid mixing) $ conda config --env --add channels conda-forge $ conda config --env --add channels defaults $ conda config --env --set channel_priority strict 2) Install Qt6 (qt6-main and qt6-multimedia) only from conda-forge Qt6 core (builds that typically include Designer/UiTools) $ conda install -y --override-channels -c conda-forge "qt6-main=6.9.3" $ conda install -y --override-channels -c conda-forge "qt6-multimedia=6.9.3" 3) Additionally, install Ruby and libgit2 only from conda-forge $ conda install -y --override-channels -c conda-forge "ruby=3.4.7" $ conda install -y --override-channels -c conda-forge "libgit2=1.9.1"

上述 conda-forge 版本约束与 macbuild/build4mac_env.py 注释中给出的推荐完全一致（qt6-main=6.9.3、qt6-multimedia=6.9.3、ruby=3.4.7、libgit2=1.9.1），且脚本期望的解释器路径即环境内的bin/python3.13与include/python3.13（见 macbuild/build4mac_env.py 的PythonAnaconda3V6）。

1. 构建：

$ cd /where/'build.sh'/exists $ ./build4mac.py -q qt6ana3 -r ana3 -p ana3

2. 确认构建成功。
3. 相同选项加-Y部署；若步骤 1 与 3 均使用--buildPymod，*.whl将部署到klayout.app/Contents/pymod-dist/：

$ ./build4mac.py -q qt6ana3 -r ana3 -p ana3 -Y

产物位于LW-qt6Ana3.pkg.macos-Sequoia-C32-release-Rana3Pana3目录（Rana3Pana3=Anaconda3 Ruby 3.4 + Anaconda3 Python 3.13）。 4. 将klayout.app安装到/Applications。 5. 由于解释器位于 conda 虚拟环境中，还需要创建一个 Automator 包装应用（Launcher）来启动 KLayout，详见Resources/script-bundle-A.zip内的Anaconda3User-ReadMeFirst.txt。

6G. 其他组合

除 6A～6F 之外，逻辑上还可以选择其他模块组合（包括nil）。选择这类"非常规"组合时，产物目录将以EX-（exceptional）为前缀——这与 macbuild/build4mac.py 中的PackagePrefix = "EX-"分支吻合。

6H. 通过代理服务器使用 git 版 Salt Package Manager

如果通过代理服务器使用基于 git 的 Salt Package Manager，需要设置KLAYOUT_GIT_HTTP_PROXY环境变量：

$ export KLAYOUT_GIT_HTTP_PROXY="http://111.222.333.444:5678"

代理服务器的实际 IP 与端口请向系统管理员索取。原文档强烈建议将此设置放入启动用的 service script bundle 中；示例脚本（*.app.Bash）可在 macbuild/Resources/script-bundle-A.zip、macbuild/Resources/script-bundle-B.zip、macbuild/Resources/script-bundle-H.zip、macbuild/Resources/script-bundle-P.zip、macbuild/Resources/script-bundle-S.zip 中找到。

7. QA 测试：用 macQAT.py 驱动 ut_runner

构建完成后可选地进行 QA 测试。macOS 环境下的 QA 工作目录为[ST|LW|HB]-build_directory.macQAT（目录中随附macQAT.py，它是ut_runner可执行文件的包装脚本）。

操作步骤（继承自原文档第 7 节）：

1. 进入 QA 工作目录：

cd [ST|LW|HB]-build_directory.macQAT

2. 打印ut_runner用法：

./macQAT.py -u

3. 仅启动 KLayout 主 GUI 窗口：

./macQAT.py -k

4. 正常运行ut_runner：

./macQAT.py -r

如有需要，可用-x <test>选项跳过个别出错测试（可多次使用，支持逗号分隔的测试名列表）。

从 macbuild/macQAT.py 源码可以看出该包装脚本的完整能力与工作原理：

• 环境变量注入（ExportEnvVariables，macbuild/macQAT.py）：TESTSRC=..（测试源目录）、TESTTMP=QATest_<Git短SHA1>_<时间戳>_<目录名>（测试临时目录），在 Darwin 上另设置DYLD_LIBRARY_PATH（指向.、db_plugins、lay_plugins、pymod）、MallocNanoZone=0以及一组ASAN_OPTIONS（关闭 leak detection、symbolize 等），这解释了"QA 所需的环境变量由macQAT.py设置"这一说明；
• -u实际执行./ut_runner --help-all；-k实际执行./klayout.app/Contents/MacOS/klayout；
• -r默认继续运行（对应ut_runner的-c），-s/--stop可切换为遇错即停；运行日志写入QATest_*.log，支持--dryrun仅打印命令行；
• 单元测试套件本身位于 src/unit_tests 与各模块的unit_tests子目录（如 src/db/unit_tests），ut_runner由 src/klayout.pro 构建体系生成。

8. 制作 DMG 安装包

使用另一个 Python 脚本 macbuild/makeDMG4mac.py 可以制作 DMG 安装包。前提：该目录是 6A～6F 中以-y/-Y选项运行build4mac.py生成的产物目录。

1. 若尚不存在，从父目录（即build.sh所在目录）为脚本建立符号链接：

makeDMG4mac.py -> macbuild/makeDMG4mac.py

2. 带-p（指定包目录）与-m（制作压缩 DMG）选项调用：

$ cd /where/'build.sh'/exists $ ./makeDMG4mac.py -p LW-qt5MP.pkg.macos-Sequoia-C32-release-Rmp34Pmp314 -m

该命令生成两个文件：

• LW-klayout-0.30.9-macOS-Sequoia-C32-1-qt5MP-Rmp34Pmp314.dmg—— 主 DMG 文件；
• LW-klayout-0.30.9-macOS-Sequoia-C32-1-qt5MP-Rmp34Pmp314.dmg.md5—— MD5 值文本文件。

DMG 文件名中的1是 DMG 序列号，可通过-s|--serial修改（默认 1）。从 macbuild/makeDMG4mac.py 的 usage 可知，脚本还支持-c/--clean（清理工作目录，与-m互斥）、-b|--bundle（强制指定 DMG 内的 bundle 名）、-u/--unsafe（跳过部分检查，慎用）、-t|--targetdmg（指定输出文件名）；其实现基于create-dmg的衍生工作，DMG 背景图与卷图标取自 macbuild/Resources 中的 PNG 与.icns资源，AppleScript 模板为 macbuild/Resources/template-KLayoutDMG.applescript。

9. 已知问题与维护要点

原文档"Known issues"一节指出：由于构建脚本假定了一些特定版本的非 OS 标准 Ruby/Python，更新 Homebrew、MacPorts 或 Anaconda3 后可能引发构建与链接错误；此时需要相应更新 macbuild/build4mac_env.py 中的字典内容（如 Ruby 3.4 的 include 目录从ruby-3.4.0变为新版本号、libruby.3.4.dylib路径变化、Homebrew Python 框架路径等）。换言之，build4mac_env.py是"版本锚点"文件，第三方软件包管理器升级后应优先核对该文件各字典项与实际安装路径是否一致。

此外结合源码还可以得到两条实用结论：

• 选择nil/非系统语言组合时，NonOSStdLang标志会被置位，-y完整部署的可用性取决于组合类型（如 HW- 包强制要求 Homebrew python@3.11，见 macbuild/build4mac.py）；
• 需要部署的 KLayout 可执行文件清单（klayout及 11 个 buddy 工具strm2cif、strm2dxf、strm2gds、strm2gdstxt、strm2lstr、strm2mag、strm2oas、strm2txt、strmclip、strmcmp、strmrun、strmxor）定义在 macbuild/build4mac_env.py 的KLayoutExecs，与原文档中"buddy 命令行工具（strm*）部署到klayout.app/Contents/Buddy/"的说明对应。

10. 小结

KLayout 的 macOS 构建体系围绕三个脚本协作：build4mac.py（构建与部署，模块组合由build4mac_env.py的字典驱动）、macQAT.py（ut_runnerQA 包装器）、makeDMG4mac.py（DMG 打包），辅以python3HB.py整理 Homebrew Python 的框架目录结构。默认路径是 MacPorts Qt5 + 系统 Ruby 2.6 + 系统 Python 3.9 的ST-标准包；追求轻量分发可选LW-组合，需要自带解释器分发的 HW*.dmg 则选择 Homebrew python@3.11 方案。对于 Qt6 或 Python 3.13/3.14 等新组合，务必以 macbuild/build4mac_env.py 中字典项注释标注的 conda-forge/MacPorts/Homebrew 具体版本号为准，以规避软件包管理器升级带来的构建链接问题。

• 硬件开发
• 桌面应用
• 图形学