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:[email protected]/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

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

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,21 @@
+---
+hide:
+  - toc
+---
+<!-- (c) https://github.com/MontiCore/monticore -->
+# Tools & Editors
+
+You have multiple options to choose from for working with SysML v2.
+You can build SysML v2 models with any text editor or integrated development environment (IDE) in combination with the [CLI](./Setup.md#run-the-cli).
+
+Though there are some editors that provide a better experience for SysML such as SysON and SysIDE.
+
+
+## Visual Studio Code
+
+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/HelloWorld.md

@@ -0,0 +1,3 @@
+<!-- (c) https://github.com/MontiCore/monticore -->
+# Hello, World!
+You're now ready to start with your first system. 

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 <fileName> [-path <p>] [-pp [<file>]] [-s [<file>]]`
+
+where the arguments are:
+
+| Option                   | Explanation                                                                                |
+|--------------------------|--------------------------------------------------------------------------------------------|
+| -ex,--extended           | Runs additional checks assuring models are fit for semantic analysis using [MontiBelle](https://www.se-rwth.de/projects/#MontiBelle) |
+| -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:
+
+```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,109 @@
+# 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/)

docs/SpesML/index.md

@@ -0,0 +1,42 @@
+# SpesML v2
+
+SpesML v2 is a modeling language based on the [SPES framework](https://www.se-rwth.de/publications/Model-Based-Systems-Engineering-with-the-SPES-Modeling-Language-A-SysML-Workbench-for-the-SPES-Methodology.pdf)
+currently in development. The SPES methodology defines a rigorous formal semantic
+applicable on the SysML v2 centered around specifying components through complete
+communication histories and stream-processing functions . The language  shown
+below is a SysML v2 profile. There are currently two types of specifications
+supported: black-box through history-oriented specifications and glass-box
+through state machines.
+
+## Exemplary Model: SumUp
+
+The following model demonstrates a simple `SumUp` component specified in SpesML v2:
+
+![SumUp](../assets/models/SumUp.bmp)
+
+```sysmlv2
+port def Naturals {
+  in attribute val: nat;
+}
+
+part def SumUp {
+  #untimed port x:  Naturals;
+  #untimed port y: ~Naturals;
+
+  satisfy requirement {
+    assume constraint InfStream {
+      x.hasInfiniteLen()
+    }
+
+    require constraint IncrementInplace {
+      forall nat t:
+        y.nth(t+1) == x.nth(t) + y.nth(t)
+    }
+  }
+}
+```
+
+The SpesML v2 leverages underspecification as a core asset for high-level specifications,
+which can be thoroughly expressed through history-oriented stream-processing specifications.
+To this end we provide a [stream library](../Reference/StreamLibrary.md) for
+stream processing functions which can be applied to streams.