SysML v2 Website

.github/workflows/gradle.yml

@@ -89,6 +89,7 @@ jobs:
 
   deploy:
     permissions:
+      contents: write
       packages: write
     runs-on: ubuntu-latest
     needs: build
@@ -114,5 +115,23 @@ jobs:
           -PnexusUser=${{ secrets.SE_NEXUS_USER }}
           -PgithubUser=${{env.GITHUB_ACTOR}}
           -PgithubToken=${{secrets.GITHUB_TOKEN}}
+          -PisPipelineFullBuild=true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create Snapshot Release
+        if: github.ref == 'refs/heads/master'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: snapshot
+          name: "Snapshot Release"
+          prerelease: true
+          files: |
+            **/*.vsix
+          body: |
+            Automated Snapshot Release
+
+            This release contains the latest development version of the SysML v2 tool and VSCode plugin.
+
+            Built from commit: ${{ github.sha }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/prepare_pages.yml

@@ -0,0 +1,52 @@
+# (c) https://github.com/MontiCore/monticore
+
+# .github/workflows/prepare_pages.yml
+name: Prepare and deploy pages
+
+# Preprocess the docs, build a site directory and push its contents to the gh-pages branch
+
+concurrency: # run this test workflow only once per branch
+  group: ${{ github.repository }}-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - docs/**
+      - mkdocs.yml
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      GITLAB_TOKEN: ${{ secrets.GITLAB_TOKEN }}
+    name: Build and Push
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+
+      - name: Install python packages
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material mike
+          git clone https://monticore:$GITLAB_TOKEN@git.rwth-aachen.de/se/infrastructure/monticore-pygments-highlighting.git
+          pip install -r ./monticore-pygments-highlighting/requirements.txt
+          pip install ./monticore-pygments-highlighting
+
+      - name: Configure Git user
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+
+      - name: Build and deploy pages
+        run: mkdocs gh-deploy --force

.gitignore

@@ -6,6 +6,10 @@ bin/
 .settings/
 .classpath/
 .gradle/
+# in gradle 8.14 "build" is currently hardcoded for the problem-reports
+build/
+
+site/
 
 # Ignore Intellij files
 *.iml

README.md

@@ -26,7 +26,7 @@ standard library package 'Vehicles' {
 
 This textual form will play a major role in the exchange of models
 between tools thus allowing to build toolchains, as well as in the
-versioning of models, e.g., in Github, and also in the efficient
+versioning of models, e.g., in GitHub, and also in the efficient
 definition of models by people who prepare textual notations.
 
 It is therefore highly relevant to have consistent parsing mechanisms
@@ -154,16 +154,16 @@ models. It provides through the CLI as follows:
 
 where the arguments are:
 
-| Option                   | Explanation                                                                                |
-|--------------------------|--------------------------------------------------------------------------------------------|
-| -ex,--extended           | Runs additional checks assuring models are fit for semantic analysis using [MontiBelle][1] |
-| -h,--help                | Prints this help dialog                                                                    |
-| -i,--input <file>        | Reads the source file (mandatory) and parses the contents                                  |
-| -path <arg>              | Sets the artifact path for imported symbols, space separated.                              |
-| -pp,--prettyprint <file> | Prints the AST to stdout or the specified file (optional)                                  |
-| -r,--report <dir>        | Prints reports of the artifact to the specified directory.                                 |
-| -s,--symboltable <file>  | Serialized the Symbol table of the given artifact.                                         |
-| -v,--version             | Prints version information                                                                 |
+| Option                   | Explanation                                                                        |
+|--------------------------|------------------------------------------------------------------------------------|
+| -ex,--extended           | Runs additional checks assuring the semantic soundness of models according to Spes |
+| -h,--help                | Prints this help dialog                                                            |
+| -i,--input <file>        | Reads the source file (mandatory) and parses the contents                          |
+| -path <arg>              | Sets the artifact path for imported symbols, space separated.                      |
+| -pp,--prettyprint <file> | Prints the AST to stdout or the specified file (optional)                          |
+| -r,--report <dir>        | Prints reports of the artifact to the specified directory.                         |
+| -s,--symboltable <file>  | Serialized the Symbol table of the given artifact.                                 |
+| -v,--version             | Prints version information                                                         |
 
 exemplary usage:
 

docs/GettingStarted/Developers.md

@@ -0,0 +1,30 @@
+<!-- (c) https://github.com/MontiCore/monticore -->
+# For Developers
+
+## Building the Tool from the Sources
+
+As alternative to a download, it is possible to build an executable JAR of the
+tool from the source files located in GitHub. In order to build an executable
+Jar of the tool with Bash from the source files available in GitHub, execute the
+following commands.
+
+First, clone the repository:
+```bash
+git clone https://github.com/MontiCore/sysmlv2.git
+```
+
+Change the directory to the root directory of the cloned sources:
+```bash
+cd sysmlv2
+```
+
+Then build the source files with gradle. To this effect, execute the following
+two command:
+
+```bash
+./gradlew :language:shadowJar
+```
+Please ensure that you have Java 21 JRE installed and gradle is set up to use it.
+
+Congratulations! The executable JAR file `language-7.*.*-SNAPSHOT-mc-tool.jar` is
+now in the directory `language/target/libs`.

docs/GettingStarted/Editor.md

@@ -0,0 +1,19 @@
+---
+hide:
+  - toc
+---
+<!-- (c) https://github.com/MontiCore/monticore -->
+# Tools & Editors
+
+We currently offer modeling support through a Visual Studio Code extension,
+integrating the MontiCore parser and applying well-formedness checks.
+
+
+## Setup
+
+1. To install VS Code, follow their [instructions](https://code.visualstudio.com/docs/setup/setup-overview).
+2. Install the SysML v2 extension.
+    1. Download the `.vsix` extension from the [releases page](https://github.com/MontiCore/sysmlv2/releases/tag/snapshot).
+    2. Start VS Code.
+    3. Go to the extension tab → Click `...` → Install from VSIX → Select the previously downloaded extension.
+

docs/GettingStarted/Setup.md

@@ -0,0 +1,27 @@
+<!-- (c) https://github.com/MontiCore/monticore -->
+# Setup SysML v2
+
+SysML v2 runs on any platform. In the following tutorials, we will use the CLI.
+
+
+#### Run the CLI
+
+To run the CLI manually, you need to have [Java 21](https://www.oracle.com/de/java/technologies/downloads/#java21) installed.
+Next, download the [SysML v2 Tool jar](https://www.monticore.de/download/MCSysMLv2.jar).
+
+You can then run the tool with:
+
+```bash
+java -jar MCSysMLv2.jar
+```
+
+exemplary usage:
+
+```
+java -jar MCSysMLv2.jar -h
+java -jar MCSysMLv2.jar -i Car.sysml -pp
+```
+
+---
+
+You can find detailed descriptions and available parameters in the [usage](./Users.md) section.

docs/GettingStarted/Users.md

@@ -0,0 +1,34 @@
+<!-- (c) https://github.com/MontiCore/monticore -->
+# For Users
+
+## Tool Download and Use
+
+* [**Download SysML v2 Tool**](https://www.monticore.de/download/MCSysMLv2.jar)
+
+The SysML v2 tool offers options for processing SysML v2 models. It provides through the CLI as follows:
+
+`java -jar MCSysMLv2.jar [-h] -i &lt;fileName&gt; [-path &lt;p&gt;] [-pp [&lt;file&gt;]] [-s [&lt;file&gt;]]`
+
+where the arguments are:
+
+| Option                   | Explanation                                                                        |
+|--------------------------|------------------------------------------------------------------------------------|
+| -ex,--extended           | Runs additional checks assuring the semantic soundness of models according to Spes |
+| -h,--help                | Prints this help dialog                                                            |
+| -i,--input &lt;file&gt;        | Reads the source file (mandatory) and parses the contents                    |
+| -path &lt;arg&gt;              | Sets the artifact path for imported symbols, space separated.                |
+| -pp,--prettyprint &lt;file&gt; | Prints the AST to stdout or the specified file (optional)                    |
+| -r,--report &lt;dir&gt;        | Prints reports of the artifact to the specified directory.                   |
+| -s,--symboltable &lt;file&gt;  | Serialized the Symbol table of the given artifact.                           |
+| -v,--version             | Prints version information                                                         |
+
+exemplary usage:
+
+```bash
+java -jar MCSysMLv2.jar -h
+java -jar MCSysMLv2.jar -i Car.sysml -pp
+```
+
+## Prerequisites
+
+To run the tool, it is required to install a Java 21 JRE.

docs/GettingStarted/index.md

@@ -0,0 +1,18 @@
+---
+icon: material/rocket-launch
+hide:
+  - toc
+---
+<!-- (c) https://github.com/MontiCore/monticore -->
+# Getting Started
+
+Let's start your SysML journey! In this chapter, we will show you how to start your first Project and introduce you to the basic concepts of SysML.
+
+We provide documentation for both **users** who want to use the SysML v2 tool and **developers** who want to build or extend it.
+
+* [For Users](./Users.md): Download and run the CLI tool.
+* [For Developers](./Developers.md): Build the tool from source and set up your development environment.
+
+!!! question "Found a problem with the documentation?"
+    If you find an error or something is not understandable, please file an [issue](../index.md#found-an-issue) for it.
+    This will help others reading the documentation in the future.

docs/Reference/StreamLibrary.md

@@ -0,0 +1,113 @@
+# Stream Library & Writing Stream Specifications
+
+The Stream Library provides standard components and definitions for working with streams in SpesML.
+Here you can find [stream expressions](https://monticore.github.io/monticore/monticore-grammar/src/main/grammars/de/monticore/Grammars/#streamexpressionsmc4-stable)
+and the [stream method library](https://github.com/MontiCore/monticore/tree/dev/monticore-libraries/stream-symbols/src/main/symtabdefinition).
+The modeling with SpesML v2 works seamlessly with the MontiCore parser.
+
+## Specifying Timing
+Timing can be specified in multiple ways using user defined keywords:
+
+1. At the interface level over ports:
+
+    ```
+    #event port x;
+    ```
+
+2. On the behavioral level:
+
+    ```
+    #sync satisfy requirement {...}
+    ```
+
+!!! warning
+    Note that 1. & 2. are **mutually** exclusive.
+
+The default timing is `event`.
+
+Stream specifications contain properties written over the input and output of components' ports.
+
+## Components
+Components use standard syntax and must declare its ports (packages beind optional):
+```
+part def A {
+  port input:   PortType1;
+  port output: ~PortType1;
+
+  ...
+}
+```
+## Ports
+Port types must exist and feature at least one attribute:
+```
+port def PortType1 {
+  attribute value: int;
+}
+```
+Attribute types have to be standardized java types (int, double, float, short, long, boolean, byte,
+ char, String), nat or user defined:
+```
+attribute def UserDefinedType1 {
+  attribute field1: int;
+}
+```
+
+```
+enum def UserDefinedEnum1 {
+  enum E1;
+  enum E2;
+}
+```
+
+## Stream Specifications
+Stream specifications can be expressed in SysML v2 as asserted constraints if there are no assumptions about the environment.
+```
+assert constraint c1 {
+  input.value == <1,2>
+}
+```
+The stream of messages over a port can be recalled by field accesses over the port usage attribute. When accessed in specifications these field accesses have an
+implicit stream type. For example `input.value` in component `A` has the type `EventStream<int>`.
+In the case of port definitions with singular attributes we provide syntactic sugar by writing `output` instead of `output.value`
+as it is unambiguous that a stream access is.
+This is especially useful when chaining methods over streams.
+
+More complex specifications can be written as assumption/guarantee pairs through requirements. Multiple assumptions and multiple guarantees are allowed.
+Each requirement corresponds to a property.
+```
+satisfy requirement r1 {
+  assume constraint c2 {
+    input.value == <1>
+  }
+  require constraint c3 {
+    output.value == input.value
+  }
+}
+```
+
+## Parameters
+Stream specifications can also be parametrized with the parameter being set at initialization of the part.
+```
+part A {
+  ...
+
+  final attribute maxValue: int;
+
+  assert constraint c4 {
+    input.value.first() >= maxValue;
+  }
+}
+```
+
+## Methods
+The stream method library and all stream expressions can be used inside specifications:
+```
+output.value.length() == (input.value()^^<2>).length()
+```
+
+## OCLExpressions
+It is usual to use first-order logic expressions in specifications. These can be embedded through OCLExpressions (which also include SetExpressions):
+```
+forall t in nat:
+  !input.value.nth(t).isEmpty() || input.values.nth(t) isIn {0}
+```

docs/Reference/index.md

@@ -0,0 +1,8 @@
+# SpesML v2 Reference
+
+Welcome to the SpesML v2 reference documentation. The SpesML v2 is constituted of a methodology and a SysML v2 language
+profile. From a technical perspective, the profile is an extension of the SysML expressions with:
+
+- [Stream Library](StreamLibrary.md)
+- [OCL expressions](https://github.com/MontiCore/ocl)
+- [MontiCore type system based on Java types](https://monticore.github.io/monticore/monticore-grammar/src/main/java/de/monticore/types3/TypeSystem3/)