Holarch

SysML v2

Das Befehlszeilenwerkzeug holarch

Prüfen, formatieren und exportieren Sie SysML v2-Modelle in Builds und CI mit dem Befehlszeilenwerkzeug holarch und der Holarch Language Engine; GitHub Actions und andere CI-Systeme, JSON- und SARIF-Berichte, Exit-Codes, Anmeldung mit einem API-Token oder einer Lizenzdatei.

So gehen Sie vor →

Auf dieser Seite
  1. Überblick
  2. Konzepte
  3. So setzen Sie es ein
    1. Wann und warum
    2. Installieren
    3. Mit einem API-Token anmelden
    4. Ein Modell prüfen
    5. Dateien formatieren
    6. Das Modell als SysML-v2-JSON exportieren
    7. In GitHub Actions ausführen
    8. In anderen CI-Systemen ausführen
    9. Ausgeführtes Beispiel: die Hybrid-Car-Demo
    10. Tipps und bewährte Vorgehensweisen
    11. Häufige Fehler
    12. Zusammenhang mit anderen Funktionen
  4. Befehle
    1. Optionen von check
    2. Optionen von format
    3. Optionen von export
    4. Optionen aller Befehle, die sich anmelden
  5. Anmeldung für das Werkzeug
    1. Lizenzdateien in CI
  6. Berichte
    1. JSON-Ausgabe
    2. SARIF
    3. GitHub-Annotationen
  7. Exit-Codes
  8. Meldungen
  9. Grenzen
  10. Verwandte Seiten

Überblick

holarch ist ein Kommandozeilenwerkzeug, das SysML-v2-Textdateien mit der Holarch Language Engine prüft, derselben Engine, die der Holarch-Editor verwendet. Führen Sie es auf Ihrem eigenen Computer oder in einem Build aus: Es liest jede .sysml-Datei in einem Ordner, meldet Probleme mit Datei, Zeile und Spalte und endet mit einem Exit-Code ungleich null, wenn das Modell Fehler hat, sodass ein Pull Request mit einem defekten Modell seine Prüfungen nicht besteht.

Das Werkzeug macht drei Dinge:

  • Prüfen: Syntax, Namen, Typen, Spezialisierungen, Multiplizitäten, Einheiten und die anderen Regeln der Engine, über alle Dateien des Modells. Berichtet als Text, JSON, SARIF (für Code-Scanning) oder GitHub-Annotationen.
  • Formatieren: schreibt Dateien in ein kanonisches Layout um (Einrückung mit vier Leerzeichen, ein Element pro Zeile, kanonische Abstände) und behält jeden Kommentar.
  • Exportieren: schreibt das Modell als SysML-v2-JSON, das Austauschformat der Systems Modeling API.

Das Werkzeug ist in den Tarifen Individual und Team (einschließlich der Testphase), in einer Lizenz der Holarch Language Engine und in einer Lizenz der selbst gehosteten Edition enthalten. Es braucht kein Holarch-Projekt: Es arbeitet mit den Dateien in Ihrem Repository.

Konzepte

  • Modell: alle .sysml-Dateien unter den angegebenen Ordnern (Standard: der aktuelle Ordner), als ein Modell gelesen. Ein in einer Datei deklarierter Name wird in den anderen aufgelöst, wie Packages in einem Holarch-Projekt. Ordner, deren Namen mit einem Punkt beginnen (etwa .git), werden übersprungen.
  • KerML-Dateien: .kerml-Dateien werden von Engine-Versionen, die KerML lesen, als KerML geprüft. Ältere Engine-Versionen führen sie als übersprungen auf, was kein Fehler ist.
  • Diagnosen: Jedes Problem hat einen Code (zum Beispiel name.unresolved), einen Schweregrad (error, warning oder note), eine Position und eine Meldung mit denselben Worten wie im Holarch-Editor. Nur Fehler lassen eine Prüfung scheitern, es sei denn, Sie fügen --warnings-as-errors hinzu.
  • Anmeldung: Das Werkzeug prüft einmal am Tag, dass Ihr API-Token zu einem Tarif Individual oder Team gehört, oder liest eine Lizenzdatei ganz ohne Netzwerkzugriff. Siehe Anmeldung für das Werkzeug.
  • Die Engine: Das Werkzeug enthält die kompilierte Holarch Language Engine und die SysML-v2-Standardbibliothek. holarch version gibt ihre Versionen und den Copyright-Hinweis der Engine aus.

So setzen Sie es ein

Wann und warum

Verwenden Sie das Werkzeug dort, wo SysML-v2-Text in einem Quellcode-Repository liegt: Entwickler bearbeiten .sysml-Dateien in einem Editor ihrer Wahl, und jede Änderung wird geprüft, bevor sie zusammengeführt wird. Es beantwortet bei jedem Commit die Frage „Hält dieses Modell noch zusammen?“, so wie ein Compiler bei Code. Verwenden Sie den Holarch-Editor zum Modellieren, für Diagramme und Prüfungen; verwenden Sie das Werkzeug, um die Dateien zwischen Bearbeitungen abzusichern. Um ein Modell zwischen dem Repository und einem Holarch-Projekt zu bewegen, verwenden Sie Import und Export.

Installieren

  1. Installieren Sie Python 3.9 oder neuer.
  2. Installieren Sie das Werkzeug für Ihr System (Linux x86-64, Linux arm64 oder macOS auf Apple Silicon) mit pip:
python3 -m pip install holarch-cli
  1. Prüfen Sie die Installation: holarch version gibt die Versionen von Werkzeug, Engine und Bibliothek aus.

Mit einem API-Token anmelden

  1. Öffnen Sie in Holarch Kontoeinstellungen → API-Token und erstellen Sie ein Token. Zugriff Nur lesen reicht aus.
  2. Legen Sie das Token in die Umgebungsvariable HOLARCH_API_KEY (in CI: ein Secret).
  3. Führen Sie holarch whoami aus. Es gibt Ihren Tarif und Ihr Konto aus, zum Beispiel "plan": "team".

Ein Modell prüfen

holarch check models/

Jedes Problem ist eine Zeile, dann folgt eine Zusammenfassung:

models/requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. Check the spelling, or import its package.
6 files checked: 1 error, 0 warnings.

Der Exit-Code ist 1, wenn das Modell Fehler hat, sonst 0. Fügen Sie --warnings-as-errors hinzu, damit auch Warnungen zum Scheitern führen.

Dateien formatieren

  1. Führen Sie holarch format models/ aus. Jede geänderte Datei wird als „reformatted <file>“ aufgeführt.
  2. Um das Layout in CI zu prüfen, ohne Dateien zu ändern, führen Sie holarch format --check models/ aus. Es listet „would reformat <file>“ auf und endet mit 1, wenn sich eine Datei ändern würde.
  3. Um die Änderungen zuerst zu sehen, führen Sie holarch format --diff models/ aus.

Eine Datei mit Syntaxfehlern wird nicht formatiert („not formatted: the file has syntax errors.“). Kommentare bleiben, wo sie waren: Notizen vor einem Element bleiben darüber, eine Notiz am Zeilenende bleibt am Ende dieser Zeile.

Das Modell als SysML-v2-JSON exportieren

holarch export models/ -o model.json

Die Datei enthält das Standard-Element-Array der Systems Modeling API. Dieselben Dateien ergeben immer dasselbe JSON, sodass der Export committet und verglichen werden kann. Ein Modell mit Fehlern wird nicht exportiert („The model has errors, so it was not exported.“); fügen Sie --force hinzu, um es trotzdem zu exportieren. Fügen Sie --holarch-fields hinzu, um zu behalten, was nur Holarch liest (Elementreihenfolge, Schreibweise), für einen exakten Import in ein Holarch-Projekt.

In GitHub Actions ausführen

  1. Fügen Sie das API-Token als Repository-Secret mit dem Namen HOLARCH_API_KEY hinzu (Settings → Secrets and variables → Actions).
  2. Fügen Sie eine Workflow-Datei hinzu, zum Beispiel .github/workflows/sysml.yml:
name: SysML model
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install holarch-cli
      - run: holarch check models --format github --sarif holarch.sarif
        env:
          HOLARCH_API_KEY: ${{ secrets.HOLARCH_API_KEY }}
      - run: holarch format --check models
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: holarch.sarif
  1. Pushen Sie. Probleme erscheinen als Annotationen an den geänderten Zeilen des Pull Requests, und der Job scheitert, wenn das Modell Fehler hat oder eine Datei nicht im kanonischen Layout ist. Lassen Sie den Schritt holarch format --check weg, um nur das Modell zu prüfen.

Der letzte Schritt lädt den SARIF-Bericht in das Code-Scanning hoch, wo Probleme unter Security → Code scanning aufgeführt werden. Lassen Sie ihn weg, wenn Ihr Repository kein Code-Scanning verwendet: Die Annotationen funktionieren auch ohne.

In anderen CI-Systemen ausführen

Jedes CI-System mit Python 3.9 oder neuer führt dieselben Befehle aus. Installieren Sie das Werkzeug, setzen Sie das Token aus einem Secret und prüfen Sie:

python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json

Zum Beispiel GitLab CI (.gitlab-ci.yml, mit HOLARCH_API_KEY als maskierter CI/CD-Variable):

sysml:
  image: python:3.12
  script:
    - pip install holarch-cli
    - holarch check models/ --sarif gl-holarch.sarif
    - holarch format --check models/
  artifacts:
    when: always
    paths: [gl-holarch.sarif]

Jenkins, Azure Pipelines, CircleCI und andere funktionieren genauso: Ein Schritt installiert das Werkzeug, der nächste führt holarch check aus; ein Exit-Code ungleich null lässt den Build scheitern. Behalten Sie den JSON-Bericht (--json) als Build-Artefakt, wenn Sie die Zahlen in einem Dashboard haben möchten.

Ausgeführtes Beispiel: die Hybrid-Car-Demo

  1. Erstellen Sie die Demo: Klicken Sie in Projekte verwalten auf Projektdateien ▾ → Neues Demoprojekt → Hybrid Car (SysML v2).
  2. Öffnen Sie Modell → Import und Export. Wählen Sie unter Exportieren Das gesamte Modell und SysML-v2-Text, klicken Sie auf Exportieren und entpacken Sie den Download in einen Ordner models Ihres Repositorys.
  3. Führen Sie holarch check models aus. Das Ergebnis ist „6 files checked: 0 errors, 0 warnings.“
  4. Ändern Sie in requirements.sysml attribute maxCurbMass : MassValue in MassValu und führen Sie die Prüfung erneut aus. Sie meldet requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. und endet mit 1.
  5. Machen Sie die Änderung rückgängig. Führen Sie einmal holarch format models aus und committen Sie die Dateien, damit spätere format --check-Läufe bestehen.
  6. Fügen Sie den GitHub-Workflow von oben hinzu. Jeder spätere Pull Request, der das Modell beschädigt, besteht seine Prüfung nicht.

Tipps und bewährte Vorgehensweisen

  • Halten Sie den Inhalt jeder Datei in einem Package. Elemente außerhalb jedes Package funktionieren, aber ein Package pro Datei hält Namen über Dateien hinweg eindeutig.
  • Verwenden Sie für CI ein schreibgeschütztes Token, beschränkt auf keine Projekte: Das Werkzeug braucht keinen Projektzugriff.
  • Formatieren Sie einmal und committen Sie das Ergebnis, bevor Sie format-check einschalten, sonst scheitert der erste Lauf an jeder Datei.
  • Legen Sie die Version des Werkzeugs in CI fest (holarch-cli==<version>), damit eine neue Engine-Version die Ergebnisse nicht mitten in einer Prüfung ändert.
  • Runner ohne Internetzugang verwenden eine Lizenzdatei statt eines Tokens.

Häufige Fehler

  • „No .sysml or .kerml files found“: Der Pfad ist falsch, oder die Dateien liegen in einem Ordner, dessen Name mit einem Punkt beginnt.
  • Namen nur in einer Datei nicht aufgelöst: Die Datei deklariert Namen, die eine andere Datei verwendet, und diese andere Datei hat einen Syntaxfehler. Beheben Sie zuerst den Syntaxfehler; der Bericht sagt, welche Dateien ausgelassen wurden.
  • Der Job scheitert mit Exit-Code 3: Das Token fehlt, ist falsch oder gehört zu einem Konto im Tarif Free. Die Meldung sagt, was zutrifft.

Zusammenhang mit anderen Funktionen

  • Die Prüfungen sind die des SysML-v2-Texts im Holarch-Editor und der Modellprüfungen für SysML-v2-Projekte, mit denselben Meldungen (Der SysML-v2-Texteditor).
  • Aus einem Projekt exportierte Dateien (Import und Export) bestehen die Prüfung fehlerfrei; das JSON, das das Werkzeug exportiert, lässt sich in ein Projekt importieren.
  • Für Änderungen, die in Holarch statt über Dateien eine Prüfung durchlaufen sollen, verwenden Sie die API oder den Python-Client, dessen Änderungen als Vorschläge ankommen.

Befehle

BefehlWas sie tut
holarch check [paths]Prüft das Modell; meldet Probleme; Exit 1 bei Fehlern
holarch format [paths]Schreibt Dateien in das kanonische Layout um
holarch export [paths]Schreibt das Modell als SysML-v2-JSON
holarch whoamiZeigt, was das Token oder die Lizenzdatei erlaubt
holarch versionGibt die Versionen von Werkzeug, Engine und Bibliothek sowie den Copyright-Hinweis der Engine aus (keine Anmeldung nötig)

Pfade sind Dateien oder Ordner; Standard ist der aktuelle Ordner. Ordner werden mit ihren Unterordnern durchsucht.

Optionen von check

OptionBedeutung
--format human|json|sarif|githubDer Bericht auf der Standardausgabe (Standard human)
--output FILEDiesen Bericht stattdessen in eine Datei schreiben
--sarif FILEZusätzlich einen SARIF-2.1.0-Bericht schreiben
--json FILEZusätzlich einen JSON-Bericht schreiben
--warnings-as-errorsAuch bei Warnungen mit 1 enden

Optionen von format

OptionBedeutung
--checkNichts ändern; mit 1 enden, wenn sich eine Datei ändern würde
--diffNichts ändern; die Änderungen als Unified Diff ausgeben
--stdoutDen formatierten Text einer Datei ausgeben, statt ihn zu schreiben

Optionen von export

OptionBedeutung
-o FILE, --output FILEIn eine Datei schreiben (Standard: Standardausgabe)
--holarch-fieldsDie Felder hinzufügen, die nur Holarch liest, für einen exakten Roundtrip
--forceEin Modell mit Fehlern exportieren (nie eines mit Syntaxfehlern)

Optionen aller Befehle, die sich anmelden

OptionUmgebungsvariableBedeutung
--api-key KEYHOLARCH_API_KEYEin API-Token (hol_…); bevorzugen Sie die Variable, damit das Token nicht in Logs landet
--license FILEHOLARCH_LICENSE_FILEEine Lizenzdatei für die Offline-Nutzung
--server URLHOLARCH_SERVERDer Holarch-Server, der das Token prüft (eine https-Adresse)
--timeout SECONDSZeitlimit für jeden Engine-Schritt (Standard 60)

Anmeldung für das Werkzeug

Das Werkzeug läuft, wenn eines davon vorhanden ist:

  • Ein API-Token eines Tarifs Individual oder Team, einschließlich der Individual-Testphase. Das Werkzeug fragt den Server einmal und behält die Antwort einen Tag lang in einer Cache-Datei (~/.cache/holarch/entitlement.json; HOLARCH_CACHE_DIR verschiebt sie). Der Cache enthält den Tarif und die E-Mail-Adresse des Kontos, nie das Token. Ist der Server nicht erreichbar, gilt eine bis zu 7 Tage alte Antwort weiterhin, mit einem Hinweis.
  • Eine Lizenzdatei, für Lizenznehmer der Holarch Language Engine, Kunden der selbst gehosteten Edition und Runner ohne Internetzugang. Das Werkzeug prüft die Signatur der Datei selbst und verbindet sich nie mit einem Server. Jede gültige Lizenz enthält das Werkzeug ohne Aufpreis:
    • Lizenz der Holarch Language Engine: Speichern Sie den Lizenzschlüssel aus Ihrer Engine-Lieferung (den Text, der mit l1. beginnt) in einer Datei, zum Beispiel holarch-engine.key, und verweisen Sie mit --license oder HOLARCH_LICENSE_FILE darauf. Zeilenumbrüche, die eine E-Mail eingefügt hat, spielen keine Rolle. Die lizenzierten Webadressen und die Servernutzung des Schlüssels gelten für die Engine in Ihrem Produkt, nicht für das Werkzeug. In den 14 Tagen nach dem Enddatum des Schlüssels arbeitet das Werkzeug weiter und gibt eine Erinnerung aus.
    • Lizenz der selbst gehosteten Edition: Verwenden Sie die Lizenzdatei Ihres Holarch-Servers unverändert. In ihren letzten 30 Tagen gibt das Werkzeug eine Erinnerung aus. In den 30 Tagen nach dem Enddatum (der Kulanzfrist der Lizenz) arbeitet das Werkzeug weiter und gibt die verbleibenden Tage aus; danach stoppt es, bis eine erneuerte Lizenz installiert ist.

Auch ein Engine-Schlüssel jenseits seiner 14 Tage stoppt das Werkzeug, bis ein erneuerter Schlüssel installiert ist.

Ein Token eines Kontos im Tarif Free wird abgelehnt, auch wenn das Konto die API über eine akademische E-Mail-Adresse behält. Die Individual-Testphase enthält das Werkzeug.

Lizenzdateien in CI

Speichern Sie die Lizenz als Secret, nie im Repository. Schreiben Sie das Secret in CI in eine Datei außerhalb des Checkouts (in GitHub Actions unter $RUNNER_TEMP) und setzen Sie HOLARCH_LICENSE_FILE auf ihren Pfad.

Berichte

JSON-Ausgabe

--format json und --json FILE schreiben:

FeldBedeutung
tool, version, engineholarch, die Version des Werkzeugs, die Version der Engine
filesDie geprüften Dateien, als Pfade relativ zu dem Ordner, in dem das Werkzeug lief
summaryerrors, warnings, notes, files
diagnosticsfile, line, column, endLine, endColumn (ab 1 gezählt), severity (error, warning, info), code, message, args
skippedNicht geprüfte Dateien, mit dem Grund (KerML-Dateien mit einer älteren Engine)
excludedDateien mit Syntaxfehlern, aus den dateiübergreifenden Prüfungen ausgelassen

Spalten zählen Unicode-Zeichen (Codepoints).

SARIF

--format sarif und --sarif FILE schreiben SARIF 2.1.0 mit einer Regel pro Diagnosecode, dem Schweregrad als error, warning oder note und Pfaden relativ zu dem Ordner, in dem das Werkzeug lief. Führen Sie das Werkzeug im Stammverzeichnis des Repositorys aus, damit das Code-Scanning die Dateien findet.

GitHub-Annotationen

--format github gibt pro Problem einen Workflow-Befehl aus (::error file=…,line=…,col=…::message), den GitHub Actions als Annotation zeigt, dann die Zusammenfassungszeile.

Exit-Codes

CodeBedeutung
0Keine Fehler (format: nichts mehr zu ändern)
1Das Modell hat Fehler; format --check oder --diff: Eine Datei würde sich ändern oder konnte nicht formatiert werden; export: wegen Fehlern abgelehnt
2Falsche Verwendung: eine unbekannte Option, ein nicht vorhandener Pfad, keine Modelldateien
3Nicht angemeldet oder nicht berechtigt: kein Token und keine Lizenzdatei, ein abgelehntes Token, ein Tarif Free, eine ungültige, veränderte oder abgelaufene Lizenzdatei
4Die Engine kann nicht laufen oder hat das Modell als zu groß oder zu langsam zum Prüfen abgelehnt

Meldungen

NachrichtBedeutung
„The holarch command line tool needs a Holarch API token of an Individual or Team plan (HOLARCH_API_KEY, or --api-key) or a Holarch Language Engine license file (HOLARCH_LICENSE_FILE, or --license).“ (Das Werkzeug braucht ein API-Token eines Tarifs Individual oder Team oder eine Lizenzdatei der Holarch Language Engine.)Weder ein Token noch eine Lizenzdatei ist gesetzt
„The holarch command line tool comes with the Individual and Team plans. Choose a plan in Account Settings → Tarif & Billing, or use a Holarch Language Engine license file.“ (Das Werkzeug ist in den Tarifen Individual und Team enthalten; wählen Sie einen Tarif unter Kontoeinstellungen → Tarif & Abrechnung oder verwenden Sie eine Lizenzdatei der Holarch Language Engine.)Das Konto des Tokens ist im Tarif Free
„The API and MCP come with the Individual and Team plans.“ (API und MCP sind in den Tarifen Individual und Team enthalten.)Das Konto des Tokens ist im Tarif Free und hat auch keinen API-Zugriff
„The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in.“ (Das API-Token ist ungültig: falsch, widerrufen oder abgelaufen, oder sein Konto kann sich nicht anmelden.)Erstellen Sie ein neues Token
„The license file's signature does not verify. Use the file exactly as it was delivered.“ (Die Signatur der Lizenzdatei lässt sich nicht verifizieren. Verwenden Sie die Datei genau so, wie sie geliefert wurde.)Die Lizenzdatei wurde verändert oder beschädigt
„License <id> expired on <date>. Install a renewed license file.“ (Die Lizenz <id> ist am <date> abgelaufen. Installieren Sie eine erneuerte Lizenzdatei.)Eine Lizenz der selbst gehosteten Edition ist vor mehr als 30 Tagen abgelaufen, oder ein Engine-Lizenzschlüssel vor mehr als 14 Tagen
„The engine license key's signature does not verify. Use the key exactly as it was delivered.“ (Die Signatur des Engine-Lizenzschlüssels lässt sich nicht verifizieren. Verwenden Sie den Schlüssel genau so, wie er geliefert wurde.)Der Schlüssel in der Datei wurde verändert oder stammt von einem anderen Produkt
„The engine license key is not complete. Copy the whole key (l1.….…) into the file.“ (Der Engine-Lizenzschlüssel ist unvollständig. Kopieren Sie den ganzen Schlüssel in die Datei.)Ein Teil des Schlüssels fehlt
„… cannot be reached to check the API token“ (… ist zum Prüfen des API-Tokens nicht erreichbar)Keine Verbindung und keine aktuelle Antwort im Cache; versuchen Sie es erneut oder verwenden Sie eine Lizenzdatei
„<file>: not formatted: the file has syntax errors.“ (nicht formatiert: Die Datei hat Syntaxfehler.)Führen Sie holarch check aus, um sie zu sehen
„<file>: not formatted: a comment could not be kept in place.“ (nicht formatiert: Ein Kommentar konnte nicht an seiner Stelle bleiben.)Die Datei bleibt unverändert; das Werkzeug verwirft nie einen Kommentar
„The model has errors, so it was not exported.“ (Das Modell hat Fehler und wurde deshalb nicht exportiert.)Beheben Sie die Fehler oder fügen Sie --force hinzu
„The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build.“ (Die installierte Engine trägt nicht den Copyright-Hinweis der Holarch Language Engine und ist daher kein echter Holarch-Build.)Installieren Sie das Werkzeug neu

Grenzen

  • Höchstens 8 MB SysML-Text pro Sprache in einem Modell und Zeilen bis 64 KB, wie im Editor.
  • Höchstens 10.000 Dateien in einem Lauf.
  • Jeder Engine-Schritt stoppt nach --timeout Sekunden (Standard 60).
  • Namen werden über Dateien derselben Sprache aufgelöst: Eine .sysml-Datei sieht keine Namen, die in einer .kerml-Datei deklariert sind.