This guide will show off the very basic way of using Sysand CLI to manage SysML v2 projects. More detailed guides will be coming soon.
To create a new project called my_project run
$ sysand new my_project
This command will create a new directory (my_project) and populate it with a minimal interchange project, consisting of two files .project.json and .meta.json.
Sysand can show some information about the project that was just created with the following commands:
$ cd my_project
$ sysand info
Name: my_project
Version: 0.0.1
No usages
$ sysand sources
*NO OUTPUT*
Currently, the project has no usages (dependencies) and no source files of its own.
For a project to be useful, it needs to have some .sysml files of its own. Create a MyProject.sysml file with the following content:
package MyProject;
Now, you can add MyProject.sysml to the project by running the following command:
$ sysand include MyProject.sysml
Including files: ["MyProject.sysml"]
The source file is now a part of the project and sysand sources can confirm:
$ sysand sources
/path/to/my_project/MyProject.sysml
All projects will have at least one dependency (called "usage" by the KerML specification) on the SysML v2 library itself, while others might have dependencies on more SysML v2 projects. The key benefit of Sysand is that it can automatically manage project dependencies for you.
KerML (and by extension 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 this website. It is also possible to install packages from the URL that points to the .kpar file.
# Install from Sysand package index
$ sysand add urn:kpar:function-library
# Install from URL
$ sysand add https://www.omg.org/spec/KerML/20250201/Function-Library.kpar
This may take a few seconds to run, as Sysand needs to download the linked project (and its usages as well) into a new local environment. Once finished, a file Sysandlock.toml and a directory sysand_env will be created. The former records the precise versions of the external projects installed, so that the same installation can be reproduced later. The latter directory stores the added project and its usages.
$ sysand info
Name: my_project
Version: 0.0.1
Usage: https://www.omg.org/spec/KerML/20240201/Semantic-Library.kpar
Running sysand sources again will list all the .sysml files from both the current project and its dependencies.
$ sysand sources
/path/to/my_project/MyProject.sysml
/path/to/my_project/sysand_env/a0e87dfa1172b094108fdacccf3a0b5a29ce7364d2e5f59f10660b24b3ff6c2b/1.0.0-beta2.kpar/TrigFunctions.kerml
/path/to/my_project/sysand_env/a0e87dfa1172b094108fdacccf3a0b5a29ce7364d2e5f59f10660b24b3ff6c2b/1.0.0-beta2.kpar/StringFunctions.kerml
...
/path/to/my_project/sysand_env/2304c62efed5f0ec8bd571d129d978c925b271914fa1d5031276a362ae2e11b4/1.0.0-beta2.kpar/FeatureReferencingPerformances.kerml
SysandLock.toml is sufficient to reproduce sysand_env; therefore, we recommend checking in SysandLock.toml into your version control system and adding sysand_env to .gitignore.
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/20240201/Data-Type-Library.kpar 1.0.0-beta2
https://www.omg.org/spec/KerML/20240201/Function-Library.kpar 1.0.0-beta2
https://www.omg.org/spec/KerML/20240201/Semantic-Library.kpar 1.0.0-beta2
If you want to recreate the environment on a new machine, make sure you have not only your project files, but also SysandLock.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
After the project reaches some maturity level, there might be a need to package it to a .kpar file for sharing with others (either through this Sysand Package Index or otherwise).
$ sysand build
$ ls output/
my_project.kpar
Sysand CLI creates a new directory output and puts the generated .kpar file there.