Command-Line Tools Reference

The fsmc toolchain provides two dedicated CLI executables:

1. fsmc: The primary compiler driver, code generator, and diagram transpiler.
2. fsm-opt: The intermediate representation optimizer, static analyzer, and pass executor.

---

1. fsmc Compiler Driver

Synopsis

fsmc -i <input_model> [OPTIONS]
fsmc [OPTIONS] <input_model>
fsmc -i <input_model> --export <format> -o <output_diagram>
fsmc -i <input_model> --verify
fsmc --export-runtime <directory_or_file> [--std 17|20]

Note on Syntax: All long options taking values support both space-separated (--option value) and assignment-style (--option=value) syntax (e.g. --output=model.hpp, --export-runtime=./runtime/).

Options Reference

Input and Output Options

Flag	Description	Default
-i, --input <file>	Path to input model file (.sysml, .slx, .puml, .mmd, .xmi, .scxml, .json, .dot), or - / /dev/stdin for standard input.	Positional argument
-o, --output <file>	Path to output generated code or exported diagram file, or - / /dev/stdout for standard output.	stdout
-t, --target <lang>	Target code generator backend: cpp (default).	cpp
-n, --name <name>	Generated state machine class/struct name.	Inferred from filename or MyFSM
-N, --ns, --namespace <ns>	Generated namespace / package / module enclosing the state machine types.	fsm_generated
--format <fmt>	Override input parser format: sysml2, stateflow, plantuml, mermaid, cameo, scxml, json, dot, auto.	auto
-e, --export <fmt>	Export diagram or formal model to: mermaid, plantuml, sysml2, stateflow, json, dot, scxml, cameo, smv.	None
-s, --sidecar <file>	Explicit companion manifest file (.fsm.yaml, .fsm.json) for diagram ingestion and external property attachment.	None
--submachine-dir <dir>	Search directory for external submachine diagram files referenced in models.	Current directory

Optimization and Code Transformation

Flag	Description	Default
-p, --pipeline <mode>	Compiler pipeline architecture: standard or 7stage (explicit 7-stage pass manager).	standard
--7stage	Shorthand alias to run the full 7-stage optimization & formal verification pipeline.	Inactive
-O0, --no-opt	Disable all middle-end optimization passes.	Enabled (-O1)
-O1	Enable standard optimization passes (canonicalization, guard simplification).	Active
-O2, --optimize	Enable aggressive optimizations including unreachable dead state and transition pruning.	Inactive
--prune, --prune-dead-states	Prune unreachable states and statically dead transitions before codegen.	false (active in -O2)
--no-simplify	Disable algebraic boolean reductions on guard expressions (--no-guard-simplification).	false
--inline, --inline-submachines	Inline modular submachines referenced via SubmachineRef into a single flat/composite FSM.	false
--pipe-through <cmd>	Stream canonical JSON IR through an external Unix filter/tool and re-read stdout.	None
--load-pass-plugin <path>	Dynamically load a C++ shared library (.so) implementing custom fsm::Pass transformations.	None

Safety, Verification and Compliance

Flag	Description	Default
verify <file>	Standalone sub-command to run formal verification, deadlocks, invariants, and LTL/CTL checks.	-
-V, --verify, --check	Run formal model checker (livelock, choice completeness, EFSM interval analysis, reachability) and exit.	false
--engine <auto\|nuxmv>	Verification engine selector (runs internal ModelChecker; for nuXmv solver execution, export via -e smv).	auto
--ltl "<formula>"	Injects an ad-hoc Linear Temporal Logic property for verification.	""
--ctl "<formula>"	Injects an ad-hoc Computation Tree Logic property for verification.	""
-Werror	Treat all compiler diagnostics and middle-end warnings as fatal errors.	false
--strict, --strict-determinism	Fail compilation on non-deterministic branch collisions or unprioritized triggers.	false
--races, --check-races	Perform static data-race analysis across parallel orthogonal regions.	false
--harness <file>	Synthesize a standalone GoogleTest C++ harness verifying MC/DC condition coverage (--emit-test-harness).	None
--req-audit	Print Requirement Traceability Matrix (@fsm:req) to terminal before code generation.	false
--rtm <file>	Export Requirement Traceability Matrix report to a file (--rtm-output).	None
--rtm-format <json\|md>	Format for Requirement Traceability Matrix export (markdown or json).	Inferred from file extension

C++ Backend Options (--target cpp)

Flag	Description	Default
--std <17\|20>	Target C++ standard (17 or 20).	17
--c++17, -std=c++17	Shortcut alias to target C++17 standard.	17
--c++20, -std=c++20	Shortcut alias to target C++20 standard.	17
--standalone	Emit self-contained header with embedded zero-alloc runtime (0 external dependencies).	true
--modular[=<hdr>]	Emit lightweight header that includes external runtime header (default: "fsm.hpp", matching --export-runtime).	false
--runtime-header <hdr>	Explicit runtime header path included when --modular is active (e.g. <fsm/fsm.hpp> or "custom/fsm.hpp").	"fsm.hpp"
--export-runtime <dir\|file>	Export standalone runtime library headers (fsm.hpp) to the specified directory or explicit file path. Directly outputs clean C++17/C++20 runtime without empty model boilerplate.	None
--no-thread-safe	Disable generation of the thread_safe_fsm asynchronous wrapper.	false
--no-stubs	Do not emit default stub functors for actions and guards.	false
--allow-diagram	Allow C++ generation from informal visual diagram formats (--allow-diagram-codegen).	false

General Options

Flag	Description	Default
--diagnostic-format <fmt>	Set diagnostic renderer output format: text (standard compiler style), json (machine readable), github (GitHub Actions ::warning / ::error annotations).	text
-h, --help	Show command-line help message and exit.	-
-v, --version	Show version information and exit.	-

---

2. fsm-opt IR Optimizer & Linter

fsm-opt operates directly on the canonical Intermediate Representation (FsmIr). It is designed for compiler developers, static analysis pipelines, and CI/CD linting gates.

Synopsis

fsm-opt -i <input_model> [OPTIONS]
fsm-opt [OPTIONS] <input_model>

Note on Syntax: All options taking arguments support both space-separated (--option value) and assignment-style (--option=value) syntax (e.g. --input=model.sysml, --output=out.json, --format=sysml2, --passes=...).

Options Reference

Input and Output Options

Flag	Description	Default
-i, --input <file>	Input model or IR file (.sysml, .puml, .mmd, .xmi, .scxml, .json, .dot, .sfx, .stateflow, .xml).	Positional argument
-o, --output <file>	Output file path for transformed IR or emitted model.	stdout
--format <fmt>	Override parser format (sysml2, plantuml, mermaid, cameo, scxml, json, dot, stateflow).	auto

Pass Pipeline and Optimization

Flag	Description	Default
--passes=<p1,p2,...>	Execute a custom comma-separated list of middle-end passes.	Standard pipeline
--list-passes	List all available registered Middle-End passes and exit.	-
--prune-dead	Enable dead state and dead transition pruning pass.	false
--pipe-through <cmd>	Stream canonical JSON IR through an external Unix filter/tool and re-read stdout.	None
--load-pass-plugin <path>	Dynamically load a C++ shared library (.so) implementing custom fsm::Pass transformations.	None
--print-before-all	Dump IR state in JSON format before executing pass pipeline.	false
--print-after-all	Dump IR state in JSON format after executing pass pipeline.	false
--diagnostic-format <fmt>	Set diagnostic output format (text, json, github).	text
-Werror	Treat all diagnostic warnings and errors as fatal (informational notes are preserved).	false

IR Serialization and Formal Emission

Flag	Description	Default
--emit-ir	Emit optimized canonical JSON Intermediate Representation.	Default
--emit-puml	Emit canonical PlantUML state diagram.	None
--emit-mmd	Emit canonical Mermaid stateDiagram-v2.	None
--emit-sysml	Emit canonical OMG SysML v2 state definition.	None
--emit-json	Emit canonical XState JSON statechart.	None
--emit-dot	Emit canonical Graphviz DOT diagram.	None
--emit-scxml	Emit canonical W3C SCXML statechart.	None
--emit-cameo	Emit canonical Cameo / MagicDraw OMG XMI 2.1 model.	None
--emit-stateflow	Emit canonical MathWorks Simulink Stateflow XML chart.	None
--emit-smv	Emit canonical nuXmv / SMV formal verification specification.	None

Analysis, Model Checking and Metrics

Flag	Description
--metrics, --stats	Display formal graph complexity, state count, and transition metrics.
--profile	Print PassManager execution timings and memory footprints.
--verify, --check	Run formal model checking passes (Safety, LTL/CTL, Reachability).

General Options

Flag	Description
-h, --help	Show command-line help message and exit.
-v, --version	Show version information and exit.

---

3. Middle-End Optimization Passes Catalogue

The fsmc middle-end provides 32 modular passes (30 standard passes across 7 pipeline stages, plus dynamic plugins and the pipe-through filter) executable via fsm-opt --passes=... or automatically configured by compiler optimization levels (-O0, -O1, -O2):

1. canonicalize: Normalizes state hierarchy, fully qualified names (FQN), and sorts nodes and transitions into deterministic order.
2. guard-simplification: Bottom-up boolean algebra reduction (not(not A) => A, A and true => A, A and false => false).
3. determinism: Enforces deterministic event dispatch ordering and validates transition priorities.
4. race-check: Static concurrency data-race analysis on shared variables accessed across parallel orthogonal regions.
5. inline-submachines: Splicing and inlining of modular SubmachineRef statecharts into a single composite hierarchy.
6. dead-state-pruning: Elimination of unreachable states and dead transition branches.
7. choice-completeness: Verifies choice pseudostate branch exhaustiveness and presence of unconditional fallback branches.
8. connective-junction-chaining: Collapses multi-hop connective junction paths into direct atomic transitions, fusing condition and transition actions into compound signatures.
9. choice-inlining: Collapses choice and junction pseudostates into direct composite transitions.
10. sampled-change-triggers: Lowers continuous stream change triggers (when (pred)) into discrete edge-triggered guards with unit-delay shadow registers (\(z^{-1}\)).
11. timed-deadlock: Detects zero-duration timeouts and racing timer invariant conflicts.
12. efsm-data-path: Abstract interpretation over numerical intervals with formal Widening (\(\nabla\)) and dead transition pruning.
13. safety-verifier: Graph reachability, deadlock traps, and livelock cycle validation.
14. model-checking: Formal symbolic verification of temporal LTL and CTL formulas against Kripke state transition graphs.
15. orthogonal-product: Cartesian product expansion and flattening of parallel orthogonal regions (\(S_A \times S_B\)).
16. wcet-analysis: Static Worst-Case Execution Time estimation, micro-step cascade bounds, and Zeno-cycle detection.
17. constant-folding: Register value propagation, boolean algebra simplification, and tautology/contradiction dead branch pruning.
18. state-minimization: Hopcroft/Moore state minimization collapsing bisimilar/equivalent states into minimal representations.
19. guard-satisfiability: SMT-based or domain-based guard unsatisfiability analysis.
20. fork-join-lowering: Lowers fork splits and join rendezvous barriers into product-state transitions.
21. history-lowering: Lowers shallow and deep history into shadow state registers.
22. deferred-event-lowering: Lowers deferred events into bounded FIFO buffers.
23. boundary-action-fusion: Flattens LCA boundary cascades into linear action sequences (exit \(\to\) transition action \(\to\) entry).
24. dead-action-elimination: Dead store elimination (DSE) across datapath variables and unused assignments.
25. register-liveness: Liveness analysis and variable interference graph construction.
26. transition-fusion: Fuses deterministic zero-time microsteps into macro-transitions.
27. common-action-factoring: Factors identical actions across convergent/divergent transition edges.
28. livelock-analysis: Detects non-progressive internal cycles.
29. priority-conflict-check: Verifies hierarchical preemption determinism and priority uniqueness.
30. timed-invariants-verifier: Formally verifies clock invariants against outgoing transition deadlines.
31. event-queue-bound: Computes static upper bound on event queue depth.
32. pipe-through: Filters and transforms IR via external Unix command.