How matlab-actions/setup-matlab works
Project Type and Purpose
• This is an open-source GitHub Action (matlab-actions/setup-matlab) implemented in TypeScript.
• Purpose: download, install, and configure MATLAB (and optional MathWorks products) on GitHub-hosted or self-hosted runners, with optional caching.
File Structure
Top-level artifacts:
• action.yml → metadata & I/O contract for the Action
• src/ → TypeScript source, subdivided into:
– index.ts → primary entrypoint (runs in “with” step)
– post.ts → post-action cleanup (runs in “post” step)
– install.ts → logic to fetch/install MATLAB via MPM
– cache-restore.ts / cache-save.ts / cache-state.ts
→ logic to restore/record/save cache
– script.ts → handles optional custom MATLAB script invocation
– mpm.ts → abstraction for MATLAB Package Manager (mpm) CLI
– matlab.ts → abstraction for MATLAB CLI details
– *.unit.test.ts → Jest tests for each module
– properties.json → static definitions consumed by toolkit
• package.json, tsconfig.json, jest.config.js → build/test configuration
• .github/workflows/*.yml → CI for lint, test, and publish
Architecture Insights from README
• Inputs: release, products, cache
• Steps in a typical workflow:
a. GitHub runner checks out code
b. “Setup MATLAB” action runs (this package)
• Pre-step (index.ts): parse inputs, try cache restore
• Install step: invoke install.ts → download MPM → run mpm install
• Post-step (post.ts): record state & save cache
c. Subsequent MATLAB-related actions use PATH
Main Components
A. GitHub Actions Runner
– executes steps defined in user workflow
– provides environment, file system, networking
B. “Setup MATLAB” Action Container
– Node.js runtime
– index.ts (main)
– post.ts (cleanup)
C. Submodules (all in src/)
1. Input Parser & Orchestrator
– reads action.yml inputs via @actions/core
2. Cache Layer
– cache-restore.ts → tries GitHub cache restore
– cache-state.ts → writes metadata for post step
– cache-save.ts → restores or saves cache
3. Installer Layer
– install.ts → pulls mpm, invokes mpm.ts
– mpm.ts → wraps mpm CLI calls
4. MATLAB Abstraction
– matlab.ts → wraps matlab CLI details
5. Script Runner (optional)
– script.ts → runs user-specified MATLAB commands
D. External Services
– GitHub Cache Service (REST API & local cache store)
– MathWorks package servers (for MPM downloads)
Component Relationships & Data Flow
1. Workflow → Runner → Action container
2. index.ts reads inputs → calls cache-restore → (if hit) populates installation directory
3. index.ts → calls install.ts → mpm.ts ↔ network ↔ MathWorks servers
4. install.ts → on success writes PATH via @actions/core
5. index.ts → if script input provided, invokes script.ts → matlab.ts
6. Post step (post.ts) retrieves cache-state → calls cache-save → cache service
7. Runner → next steps in workflow
Architectural Patterns & Principles
• Single Responsibility: each module handles one concern (cache, install, script)
• Orchestration vs. implementation separation: index.ts & post.ts orchestrate, modules implement
• Declarative metadata (action.yml) driving dynamic behavior
• Layered external interaction: Node.js → GitHub Actions Toolkit → GitHub Services / OS / Network