Getting started

To get started with Sysand, first follow the instructions for installing Sysand, then try out the steps in the tutorial.

Installation
Tutorial

Installation

Sysand is written in Rust programming language. To build it, install Rust and run the following command in the terminal:

cargo install sysand --git=https://github.com/sensmetry/sysand.git

With Sysand installed, you can now create a model interchange project as shown in the following subsection.

Tutorial

Model interchange projects

A model interchange project is a collection of SysML v2 (.sysml) or KerML (.kerml) files with additional metadata such as project name, versions, and the list of projects on which it depends. To create a new project called my_project run:

$ sysand new my_project
    Creating interchange project `my_project`

This creates a new directory (my_project) and populates it with a minimal interchange project, consisting of two files .project.json and .meta.json.

Inside the directory, we can ask for a basic overview of the project.

$ cd my_project
$ sysand info
Name: my_project
Version: 0.0.1
No usages.

Source files

The project we created in the previous subsection contains no source files as can be seen by running the following command:

$ sysand sources
<NO OUTPUT>

Before we can add source files to the project, we need to create them. Create MyProject.sysml file with the following content:

package MyProject;

Now, we can add MyProject.sysml to our project by running the following command:

$ sysand include MyProject.sysml
   Including files: ["MyProject.sysml"]

The file will now be listed by sysand sources, which can serve as the input to a SysML v2 processing environment.

$ sysand sources
/path/to/my_project/MyProject.sysml

The following subsection shows how to add dependencies to our project.

Dependencies

Effectively all projects depend on elements defined in other projects. The key benefit of Sysand is that it can automatically manage project dependencies for you.

KerML (and by extension in SysML v2) specification calls a project dependency a usage. Each usage is identified by an Internationalized Resource Identifier (IRI) with an optional version constraint. To add dependencies, use the sysand add command. The simplest way to use it is to give an IRI to a package you want to install from the Sysand Package Index. You can find the IRI (and the full install command) in the card of the package on the index website. For example, to install the standard Function Library, run:

$ sysand add urn:kpar:function-library
      Adding usage: urn:kpar:function-library
    Creating env
     Syncing env
  Installing urn:kpar:semantic-library 1.0.0
  Installing urn:kpar:data-type-library 1.0.0
  Installing urn:kpar:function-library 1.0.0

It is also possible to install packages from the URL that points to the .kpar file as shown in the following snippet:

$ sysand add https://www.omg.org/spec/KerML/20250201/Function-Library.kpar
      Adding usage: https://www.omg.org/spec/KerML/20250201/Function-Library.kpar
    Creating env
     Syncing env
  Installing https://www.omg.org/spec/KerML/20250201/Semantic-Library.kpar 1.0.0
  Installing https://www.omg.org/spec/KerML/20250201/Data-Type-Library.kpar 1.0.0
  Installing https://www.omg.org/spec/KerML/20250201/Function-Library.kpar 1.0.0

Adding a dependency may take a few seconds to run, as it will find and install the project (and any transitive usages) into a new local environment. Once finished, this will have created a file called sysand-lock.toml and a directory sysand_env. The former records the precise versions installed, so that the same installation can be reproduced later. The latter directory will contain a local installation of the added project, as well as any of its (transitive) usages. sysand-lock.toml is sufficient to reproduce sysand_env; therefore, we recommend checking in sysand-lock.toml into your version control system and adding sysand_env to .gitignore.

We can confirm that the usage was successfully added by running the info command again:

$ sysand info
Name: my_project
Version: 0.0.1
Usages:
    https://www.omg.org/spec/KerML/20250201/Semantic-Library.kpar

If we run sysand source again, it will now include all source files of the set of (transitive) dependencies.

$ sysand sources
/path/to/my_project/sysand_env/7afe310696b522f251dc21ed6086ac4b50a663969fd1a49aa0aa2103d2a674ad/1.0.0.kpar/Metaobjects.kerml
/path/to/my_project/sysand_env/7afe310696b522f251dc21ed6086ac4b50a663969fd1a49aa0aa2103d2a674ad/1.0.0.kpar/Performances.kerml
/path/to/my_project/sysand_env/7afe310696b522f251dc21ed6086ac4b50a663969fd1a49aa0aa2103d2a674ad/1.0.0.kpar/Links.kerml
/path/to/my_project/sysand_env/7afe310696b522f251dc21ed6086ac4b50a663969fd1a49aa0aa2103d2a674ad/1.0.0.kpar/SpatialFrames.kerml
/path/to/my_project/sysand_env/7afe310696b522f251dc21ed6086ac4b50a663969fd1a49aa0aa2103d2a674ad/1.0.0.kpar/Clocks.kerml
...

Environments

When we executed sysand add in the previous subsection, it implicitly created and synchronized an environment for us. For users familiar with Python, Sysand environments serve the same purpose as Python virtual environments: they store dependencies needed for a specific project.

We can see everything installed in the local environment using sysand env list:

$ sysand env list
https://www.omg.org/spec/KerML/20250201/Data-Type-Library.kpar 1.0.0
https://www.omg.org/spec/KerML/20250201/Function-Library.kpar 1.0.0
https://www.omg.org/spec/KerML/20250201/Semantic-Library.kpar 1.0.0

If you want to recreate the environment on a new machine, make sure you have not only your project files, but also sysand-lock.toml and execute the following command:

$ sysand sync
    Creating env
     Syncing env
  Installing https://www.omg.org/spec/KerML/20250201/Data-Type-Library.kpar 1.0.0
  Installing https://www.omg.org/spec/KerML/20250201/Semantic-Library.kpar 1.0.0
  Installing https://www.omg.org/spec/KerML/20250201/Function-Library.kpar 1.0.0

Packaging projects for distribution

To package your project for distribution, run sysand build:

$ sysand build
    Building kpar: /path/to/my_project/output/my_project.kpar

This command creates a my_project.kpar file that can be installed in a different project using sysand.

Project information and metadata

Contents of interchange project information (.project.json) and metadata (.meta.json) files are specified in KerML specification. Sysand imposes extra requirements for some fields, as documented below. These extra requirements are imposed to achieve better interoperability and aid in machine processing.

Fields

`license`

Specification does not have any requirements for license format. Sysand encourages the use of SPDX License Expressions to specify licenses. By default Sysand rejects license strings that are not valid SPDX License Expressions. Examples of valid expressions:

MIT - MIT license
MIT OR Apache-2.0 - MIT and/or Apache-2.0 license applies, chosen by the user
LicenseRef-My-License - a custom license (LicenseRef- part is mandatory in this case). This should be used when the license used is not in SPDX License list.

See the specification and license list for more information. If a project’s license is not given, it is assumed that the project cannot be used under any license.

As specified by REUSE project, license files should be included at the top level directory of the project inside LICENSES subdirectory. License file name should match the license field’s value with .txt appended, except when using composite expressions (those containing OR, AND or WITH). In those cases include all the license/exception files mentioned in the expression. For the complete set of SPDX license and exception files, see the SPDX GitHub repository. Custom licenses (such as LicenseRef-MyCustom) result in license file name LicenseRef-MyCustom.txt.

Each file should have its license specified at the top in a comment. See REUSE spec for details.

`version`

Specification does not impose any constraints on how the version should look like, it only recommends to use Semantic Versioning (SemVer). Sysand strongly encourages users to use SemVer and by default does not accept non-SemVer 2.0.0 version strings in its commands.

`versionConstraint`

versionConstraint field can be used to constrain the allowed versions of a specific project within a usage.

Version constraints use the same syntax as Rust’s Cargo. The usage resolution version selection mechanism is only implemented for semantic version constraints and semantic versions of used projects. Sysand will not be able to correctly (or at all) select versions for usages that do not adhere to SemVer.

See below for details.

Version constraint syntax

A version constraint consists of one or more version comparators, separated by commas. Each version comparator consists of an operator and a version. Version is a SemVer with possibly omitted trailing components, e.g. 1.0.0, 2.3, 5, 2.3.4-beta are all valid in a comparator. The missing components are ignored when matching against a version. Note that versions can only be truncated in version constraints, but not in any other context. In order for the version to satisfy a constraint, it must match all of the comparators in the constraint.

Version comparison operators are listed below. In the examples, := denotes equivalence between expressions.

No operator

A bare version specifier, such as 1.2.3, 2, 3.1. It is exactly equivalent to a caret (^) operator.

Caret operator

Caret operator (^) allows SemVer compatible updates.

Leaving off the caret is a simplified equivalent syntax. It is recommended to use the caret syntax for added clarity.

Versions are considered compatible if their left-most non-zero major/minor/patch component is the same. This is different from SemVer which considers all pre-1.0.0 packages to be incompatible.

Examples:

^1.2.3  := 1.2.3 := >=1.2.3, <2.0.0
^1.2    := 1.2   := >=1.2.0, <2.0.0
^1      := 1     := >=1.0.0, <2.0.0
^0.2.3  := 0.2.3 := >=0.2.3, <0.3.0
^0.2    := 0.2   := >=0.2.0, <0.3.0
^0.0.3  := 0.0.3 := >=0.0.3, <0.0.4
^0.0    := 0.0   := >=0.0.0, <0.1.0
^0      := 0     := >=0.0.0, <1.0.0

Tilde operator

Tilde operator (~) specifies a minimal version with some ability to update. If a major, minor, and patch version or only a major and minor version is specified, only patch-level changes are allowed. If only a major version is given, then minor- and patch-level changes are allowed.

Examples:

~1.2.3  := >=1.2.3, <1.3.0
~1.2    := >=1.2.0, <1.3.0
~1      := >=1.0.0, <2.0.0

Wildcard operator

Wildcard operator (*) allows for any version where the wildcard is positioned.

Examples:

*     := >=0.0.0
1.*   := >=1.0.0, <2.0.0
1.2.* := >=1.2.0, <1.3.0

Equals operator

Equals operator (=) means the exact version is required. Since the version in a comparator may be partial, only the parts specified are required to match exactly.

Examples:

=1.2.3 := >=1.2.3, <1.2.4
=1.2   := >=1.2.0, <1.3.0
=1     := >=1.0.0, <2.0.0

Comparison operators

Comparison operators (<, <=, >, >=) are the most basic, as all the other comparators can be equivalently translated to (possibly multiple) comparison comparators. If only one comparison operator is given, the allowed versions range has no opposite end.

Examples:

>=1.2.0
>1      := >=2.0.0
<2      :=  <2.0.0
<=1.5   :=  <1.6.0

Multiple comparators

As mentioned and shown in the examples above, multiple version comparators can be used in a single constraint when separated with a comma, e.g., >=1.2, <1.5. All comparators in a constraint must be satisfied, so a non-overlapping constraint like <1.2, ^1.2.2 is unsatisfiable.

Pre-releases

Version constraints exclude pre-release versions, such as 1.0.0-alpha, unless specifically asked for, i.e. the exact same version with any pre-release tag must be used in a comparator in order for that comparator to try to match the pre-release versions.

Pre-release versions are considered to be lower than regular versions in SemVer spec. Comparators specifying a pre-release tag can also match regular versions.

Examples:

constraint 1.0 will not be satisfied by version 1.0.0-alpha
constraint >=1.0.0-beta.2, <2.0.0-alpha.5 will be satisfied by version 1.2.3-rc.2
constraint >=5.4.2-beta1 will be satisfied by versions 5.4.2, 6.2.0 and 5.4.2-rc, but not 5.4.3-alpha
constraint ^1.2.3-rc will be satisfied by version 1.2.3

Version metadata

Version metadata, such as 1.0.0+21AF26D3, is ignored and should not be used in version requirements.

More information

See Cargo docs, semver crate docs (semver crate is used by both Sysand and Cargo for version selection) and SemVer specification for more detailed information regarding version constraints and semantic versioning.

Commands

Commands available for `sysand`

init
new
add
remove
include
exclude
build
lock
env
- install
- uninstall
- list
- sources
sync
info
sources
print-root

`sysand init`

Create new project in current directory

Keyboard shortcuts

Sysand User Guide