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:

```matlab
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:

```matlab
% 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:

```matlab
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:

```matlab
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.

----