matlab-build-toolbox

matlab-build-toolbox — Build Executor

You execute the build pipeline. You are an operator — you introspect the plan to find the right task to invoke, run it, report results at each stage, and stop on failure. This is the only skill in the pipeline with no human checkpoint.

When to Use

• After matlab-assess-toolbox reports READY (no blockers)
• User says "build it", "run the build", or "build package"
• User has their own buildfile.m and wants to execute it
• As part of the full pipeline after readiness gate passes

When NOT to Use

• No buildfile.m exists — use matlab-create-buildfile first
• User wants to create or modify build tasks — use matlab-create-buildfile
• User wants to publish/release — use matlab-publish-toolbox after a successful build
• User wants a readiness check — use matlab-assess-toolbox

Key Functions

Function	Purpose
matlab.buildtool.Plan.load	Introspect the build plan to discover tasks and dependencies
buildtool	Execute the build pipeline (runs task dependency chain)
dir	Locate and verify the .mltbx artifact after packaging

Inputs

• project_root: Path to the project (default: current directory)
• target (optional): The buildtool task to execute. If omitted, auto-detected from the plan (see Step 2).

Workflow

Step 1 — Verify Preconditions

Before executing:

1. Confirm buildfile.m exists at the project root
2. Determine pipeline context:
   • Full pipeline (buildUtilities/toolboxSpecification.m and buildUtilities/tbxManifest.m exist): readiness was run, proceed with full context
   • Standalone buildplan (only buildfile.m exists): user has their own plan not generated by matlab-create-buildfile. Skip spec/manifest checks, proceed with introspection.
3. If full pipeline context exists, confirm no blockers from last readiness check

If buildfile.m does not exist, stop and direct the user to matlab-create-buildfile or ask them to provide one.

Step 2 — Introspect the Build Plan

Load the plan and discover its structure:

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

Identify the target task (in priority order):

1. Use the target input if provided
2. Look for a task named package
3. Find the terminal task — one with no downstream dependents that produces the .mltbx
4. If ambiguous (multiple candidates), ask the user which to run

Identify the dependency chain leading to the target:

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

Report what will execute:

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

Step 3 — Execute Build Pipeline

Run via MATLAB, stopping on first failure:

buildtool <target>

Monitor each stage dynamically based on what's in the chain:

Task Type	Success Condition	On Failure
CodeIssuesTask or "check"	0 error-severity findings	Report findings, stop
TestTask or "test"	All tests pass	Report failures, stop
Coverage (if present)	Reports coverage	Log warning if below threshold (does not stop)
MexTask	MEX file produced	Report error, stop
PcodeTask	P-code files produced	Report error, stop
Packaging task	.mltbx file produced	Report error, stop

Not all chains have all stages. Report only what exists in this plan.

Step 4 — Verify Artifact

After successful packaging, locate and verify the .mltbx. First check the task's declared Outputs (authoritative), then fall back to scanning release/ and the project root:

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);

If no .mltbx in release/, check the task's declared Outputs or scan the project root. A zero-byte file counts as a failure.

Step 5 — Report Results

## 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")

Adapt the report to what actually ran — omit sections for stages not in this plan (e.g., if no coverage task, don't report coverage).

On failure:

## Build Failed — [Stage]

### What happened
[error details]

### Suggested fix
[actionable suggestion]

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

Output

• .mltbx toolbox package
• Build report (pass or fail with details)

Checkpoint

No — this skill is mechanical. It executes an already-approved plan. If it fails, it reports why and stops.

Key Rules

• Introspect first. Read the buildplan before executing. Never assume the task name or dependency chain — discover it.
• Stop on first failure. Never continue past a failing stage. A package from broken code is worse than no package.
• Report everything. Show counts, percentages, durations. The user should be able to verify the build quality.
• Verify the artifact. Check .mltbx exists and has non-zero size. A zero-byte package is a silent failure.
• No decisions. You execute the plan. You do not modify code, skip tests, or lower thresholds. If something fails, report it and stop.
• Idempotent. Running this skill again after fixing an issue should work cleanly.

Next Steps

• /matlab-publish-toolbox — version-stamp and distribute the release

---

Copyright 2026 The MathWorks, Inc.

---