matlab-build-toolbox

matlab-build-toolbox — 构建执行器

你将执行构建流水线。你是一名操作员——你会检查计划，找到要调用的正确任务，运行该任务，在每个阶段报告结果，并在失败时停止。这是流水线中唯一没有人工检查点的技能。

适用场景

• matlab-assess-toolbox 报告 READY（无阻塞项）后
• 用户说“构建它”“运行构建”或“构建包”
• 用户有自己的 buildfile.m，并希望执行它
• 就绪检查通过后，作为完整流水线的一部分

不适用场景

• 不存在 buildfile.m——先使用 matlab-create-buildfile
• 用户想要创建或修改构建任务——使用 matlab-create-buildfile
• 用户想要发布／发行——成功构建后使用 matlab-publish-toolbox
• 用户想要进行就绪检查——使用 matlab-assess-toolbox

关键函数

函数	用途
matlab.buildtool.Plan.load	检查构建计划，以发现任务和依赖关系
buildtool	执行构建流水线（运行任务依赖链）
dir	定位并验证打包后的 .mltbx 产物

输入

• project_root：项目路径（默认：当前目录）
• target（可选）：要执行的 buildtool 任务。若未提供，则从计划中自动检测（参见步骤 2）。

工作流

步骤 1 — 验证前置条件

执行前：

1. 确认项目根目录下存在 buildfile.m
2. 确定流水线上下文：
   • 完整流水线上下文（存在 buildUtilities/toolboxSpecification.m 和 buildUtilities/tbxManifest.m）：已执行就绪检查，可继续并使用完整上下文
   • 独立 buildplan（仅存在 buildfile.m）：用户使用的是自己的计划，而非由 matlab-create-buildfile 生成的计划。跳过规格／清单检查，继续检查计划。
3. 如果存在完整流水线上下文，确认上次就绪检查没有阻塞项

如果不存在 buildfile.m，请停止，并引导用户使用 matlab-create-buildfile 或让用户提供一个文件。

步骤 2 — 检查构建计划

加载计划并发现其结构：

plan = matlab.buildtool.Plan.load("buildfile.m");
disp({plan.Tasks.Name})

确定目标任务（按优先级排序）：

1. 如果提供了 target 输入，则使用它
2. 查找名为 package 的任务
3. 找出终端任务——即没有下游依赖项且会生成 .mltbx 的任务
4. 如果无法确定（存在多个候选项），询问用户要运行哪个任务

确定指向目标任务的依赖链：

% The chain executes in topological order when you run the target
% e.g., buildtool package → runs check, test, package

报告将执行的内容：

Build target: "package"
Dependency chain: check → test → package

步骤 3 — 执行构建流水线

通过 MATLAB 运行，首次失败时停止：

buildtool <target>

根据依赖链中的任务动态监控各个阶段：

任务类型	成功条件	失败时
CodeIssuesTask 或 “check”	错误严重级别的发现项为 0	报告发现项并停止
TestTask 或 “test”	所有测试均通过	报告失败并停止
覆盖率（如果存在）	报告覆盖率	如果低于阈值，则记录警告（不停止）
MexTask	已生成 MEX 文件	报告错误并停止
PcodeTask	已生成 P 代码文件	报告错误并停止
打包任务	已生成 .mltbx 文件	报告错误并停止

并非所有依赖链都包含全部阶段。只报告此计划中存在的阶段。

步骤 4 — 验证产物

成功打包后，定位并验证 .mltbx。先检查任务声明的 Outputs（权威来源），然后再扫描 release/ 和项目根目录：

mltbxFile = dir(fullfile("release", "*.mltbx"));
assert(~isempty(mltbxFile), "No .mltbx file found in release/");
assert(mltbxFile(1).bytes > 0, "Package file is empty");
fprintf("Package: %s (%.1f KB)\n", fullfile(mltbxFile(1).folder, mltbxFile(1).name), mltbxFile(1).bytes / 1024);

如果 release/ 中没有 .mltbx，则检查任务声明的 Outputs，或扫描项目根目录。大小为零的文件视为失败。

步骤 5 — 报告结果

## Build Complete

- Package: release/MyToolbox.mltbx (142.3 KB)
- Target: "package"
- Chain: check → test → package
- Static analysis: 0 errors, 2 warnings
- Tests: 25/25 passed
- Coverage: 85%
- Duration: 12.3s

### Next Steps
- Run `matlab-publish-toolbox` to version-tag and release
- Test installation: matlab.addons.toolbox.installToolbox("release/MyToolbox.mltbx")

根据实际运行的内容调整报告——省略此计划中不存在的阶段（例如，没有覆盖率任务时，不要报告覆盖率）。

失败时：

## Build Failed — [Stage]

### What happened
[error details]

### Suggested fix
[actionable suggestion]

### To retry
Run `matlab-build-toolbox` after fixing the issue.

输出

• .mltbx 工具箱包
• 构建报告（包含通过或失败的详情）

检查点

无——此技能只执行机械操作，用于执行已获批准的计划。如果执行失败，则报告原因并停止。

核心规则

• 先检查。 执行前先阅读 buildplan。切勿假设任务名称或依赖链——请先确认。
• 首次失败即停止。 任何阶段失败后都不要继续。由有问题的代码生成的程序包比没有程序包更糟。
• 报告所有信息。 显示数量、百分比和耗时。用户应能验证构建质量。
• 验证构件。 检查 .mltbx 是否存在且大小不为零。零字节程序包意味着静默失败。
• 不做决定。 按计划执行。不要修改代码、跳过测试或降低阈值。如果某项失败，请报告并停止。
• 保持幂等。 修复问题后再次运行此技能，应能顺利完成。

后续步骤

• /matlab-publish-toolbox — 为版本添加标记并分发

---

版权所有 2026 The MathWorks, Inc.

---