MARTe Development Tools (mdt)

mdt is a comprehensive toolkit for developing, validating, and building configurations for the MARTe real-time framework. It provides a CLI and a Language Server Protocol (LSP) server to enhance the development experience.

WARNING

This code has been mostly generated by AI.

Features

• Portability: A single statically compiled executable compatible with any Linux 3.2+ machine (as well as possible to compile and run on Windows and Mac OS X)
• LSP Server: Real-time syntax checking, validation, autocomplete, hover documentation, navigation (Go to Definition/References), Inlay Hints (inline types and evaluation), and hierarchical Document/Workspace Symbols.
• Signal Flow Graph: Interactive browser-based visualisation of GAM/DataSource signal flow, with state/thread filtering, focus layouts, watchlists, and live reload.
• Builder: Merges multiple configuration files into a single, ordered output file.
• Formatter: Standardizes configuration file formatting.
• Validator: Advanced semantic validation using CUE schemas, ensuring type safety and structural correctness.

MARTe extended configuration language

Few additional features have been added to the standard MARTe configuration language:

• Multi file configuration support
  • Multi file definition merging
  • File level namespace / node (#package)
• Variables and Constants
  • Overrideable variables (#var)
  • Fixed constants (#let)
  • Powerful expressions (arithmetic, bitwise, string concatenation)
• Doc-strings support (//#) for objects, fields, and variables
• Logic and Templates
  • Conditional blocks (#if, #else)
  • Loops (#foreach over arrays)
  • Reusable parameterized templates (#template, #use)
• Pragmas (//!) for warning suppression / documentation

Documentation

• Step-by-Step Tutorial
• Editor Integration Guide
• Configuration Guide
• Signal Flow Graph Guide
• Examples Readme

Installation

From Source

Requirements: Go 1.21+

go install github.com/marte-community/marte-dev-tools/cmd/mdt@latest

Usage

CLI Commands

• Init: Initialize a MARTe project.

  mdt init project_name

• Check: Run validation on a file or project.

  mdt check [-P folder_path] [-p project_name] [-vVAR=VAL] <input_files...>

• Build: Merge project files into a single output.

  mdt build [-P folder_path] [-p project_name] [-o output.marte] [-vVAR=VAL] <input_files...>

• Format: Format configuration files.

  mdt fmt path/to/file.marte

• Graph: Open an interactive signal-flow graph in the browser.

  mdt graph [-P folder_path] [-p project_name] [-port PORT] [-vVAR=VAL] [files...]

• LSP: Start the language server (used by editor plugins).

  mdt lsp [--graph [--graph-port=PORT]]

Editor Integration

mdt lsp implements the Language Server Protocol. You can use it with any LSP-compatible editor (VS Code, Neovim, Emacs, etc.).

MARTe Configuration

The tools support the MARTe configuration format with extended features:

• Objects: +Node = { Class = ... }
• Signals: Signal = { Type = ... }
• Namespaces: #package PROJECT.NODE for organizing multi-file projects.

Validation & Schema

Validation is fully schema-driven using CUE.

• Built-in Schema: Covers standard MARTe classes (StateMachine, GAM, DataSource, RealTimeApplication, etc.).
• Custom Schema: Add a .marte_schema.cue file to your project root to extend or override definitions.

Example .marte_schema.cue:

package schema

#Classes: {
    MyCustomGAM: {
        #meta: {
            direction: "INOUT"
            multithreaded: true
        }
        Param1: int
        Param2?: string
        ...
    }
}

Pragmas (Suppressing Warnings)

Use comments starting with //! to control validation behavior. Pragmas can be placed locally (above a specific field or object) or globally (at the top of the file to affect the whole project/file).

Supported Pragmas:

• //! ignore(tag) or //! allow(tag): Suppress a specific diagnostic.
• //! cast(DefinedType, UsageType): Allow type mismatch between signal definition and usage (e.g., //! cast(uint32, int32)).

Common Diagnostic Tags:

Tag	Level	Description
unused_gam	Warning	GAM is defined but not used in any thread.
unused_signal	Warning	Signal is defined in DataSource but never referenced.
implicit_signal	Warning	Signal is used in a GAM but not explicitly defined in the DataSource.
parent_mismatch	Error	Object is placed under an invalid parent (validated via schema).
datasource_direction	Error	Signal usage violates DataSource direction (IN/OUT/INOUT).
datasource_threading	Error	Non-multithreaded DataSource used in multiple threads.
not_produced	Error	INOUT Signal consumed before being produced in a thread.
not_consumed	Warning	INOUT Signal produced but never consumed in a thread.
duplicate_field	Error	Field is defined multiple times in the same node.
unknown_class	Warning	Class name not found in the CUE schema.
schema_validation	Error	General CUE schema violation (missing mandatory fields, wrong types).
unknown_reference	Error	Identifier reference could not be resolved.
signal_type_mismatch	Error	Signal has different types in different GAMs/DataSources.
variable_value_mismatch	Error	Variable value does not match its declared type.

Example Global Suppression:

//! ignore(unused_gam)
//! ignore(implicit_signal)
#package MyProject
...

Example Local Suppression:

//! ignore(parent_mismatch)
+InvalidParent = {
    Class = "MyClass"
}

Development

Building

go build ./cmd/mdt

Running Tests

go test ./...

License

MIT