Creating your first project

In this tutorial you will create a Sysand project from scratch: initialize it, add a model file, add a dependency, use that dependency in your own model, and package the project for sharing. Along the way you will meet the commands you will use most in day-to-day work. No prior experience with package managers is needed.

To follow along, you need Sysand installed. See Installation if you have not done that yet.

Initialize a new project using Sysand CLI

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 init my-project
    Creating interchange project `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. To instead create a new project in the current directory, omit the path (my-project in this case). In that case, the project’s name will be the same as the current directory name.

Inspect the project

Sysand can show some information about the project that was just created with the following commands:

$ cd my-project
$ sysand info
Name: my-project
Publisher: untitled
Version: 0.0.1
No usages.

Note

The command also prints a warning about standard libraries. You can safely ignore it (we omit it from the outputs in this tutorial): standard libraries are usually provided by your SysML v2 tooling, so Sysand leaves them out unless asked with --include-std (see sysand sources).

$ sysand sources

The command prints nothing yet: the project has no usages (dependencies) and no source files of its own.

Add source files

For a project to be useful, it needs to have some .sysml/.kerml files of its own. Create a MyProject.sysml file with the following contents:

package MyProject;

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

$ sysand include MyProject.sysml
   Including file `MyProject.sysml`

The source file is now a part of the project, which sysand sources can confirm:

$ sysand sources
/path/to/my-project/MyProject.sysml

Add usages (dependencies)

KerML (and by extension SysML v2) specification calls a project dependency a “usage”. All SysML v2 projects will have at least one dependency on the SysML v2 standard library itself, and many will have dependencies on more SysML v2 projects. The key benefit of Sysand is that it can automatically manage project dependencies for you.

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 Index. You can find the IRI (and the full install command, with a copy button) in the install bar at the top of the project’s page on the index. It is also possible to install packages from the URL that points to the .kpar file or to a directory that contains the project.

Install usage DETECT from Sysand Index:

$ sysand add sensmetry/detect
      Adding usage: `pkg:sysand/sensmetry/detect`
    Creating env
     Syncing env
  Installing `pkg:sysand/sensmetry/detect` 1.3.0-dev

Note

The version you see may be newer than the 1.3.0-dev shown here. Directory names and version numbers in the outputs below follow whatever version was installed, so expect the same difference there.

This may take a few seconds to run, as Sysand needs to download the project (and its usages as well) into a new local environment. Once finished, a file sysand-lock.toml and a directory .sysand 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
Publisher: untitled
Version: 0.0.1
Usages:
    pkg:sysand/sensmetry/detect

Running sysand sources again will list all the .sysml files from both the current project and its (transitive) dependencies. The order of the files may vary.

$ sysand sources
/path/to/my-project/MyProject.sysml
/path/to/my-project/.sysand/lib/sensmetry-detect_1.3.0-dev/detect_definitions.sysml
/path/to/my-project/.sysand/lib/sensmetry-detect_1.3.0-dev/detect_input.sysml
/path/to/my-project/.sysand/lib/sensmetry-detect_1.3.0-dev/detect_requirement_list.sysml
/path/to/my-project/.sysand/lib/sensmetry-detect_1.3.0-dev/detect_criteria_list.sysml
/path/to/my-project/.sysand/lib/sensmetry-detect_1.3.0-dev/detect_use_cases.sysml

Tip

sysand-lock.toml is sufficient to reproduce .sysand on any computer; therefore, we recommend checking in sysand-lock.toml into your version control system and adding .sysand to .gitignore (or equivalent).

Use the dependency in your model

Installing a dependency pays off when your own model refers to it. The detect project’s source files define SysML v2 packages such as DETECT_Sizing. You can see the package names by opening the installed files under .sysand/lib/, or by browsing the project’s files on its page on the index.

Replace the contents of MyProject.sysml with the following, which imports the DETECT_Sizing package and uses its DE_Ecosystem part definition:

package MyProject {
    private import DETECT_Sizing::*;

    part my_ecosystem : DE_Ecosystem;
}

There is no need to run sysand include again: the file is already part of the project, and Sysand tracks files, not their contents.

Resolving the name DE_Ecosystem is the job of your SysML v2 tool, not of Sysand: point the tool at every file listed by sysand sources, and the import will resolve because the file defining DETECT_Sizing is on that list. What you can check right here is that the list is complete: run sysand sources again and confirm it shows both MyProject.sysml and the detect files, as in the previous section.

List installed dependencies

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
`pkg:sysand/sensmetry/detect` 1.3.0-dev

Note

The environment can also contain projects that are not dependencies of the current project, because projects are never automatically removed from it; see sysand env list.

If you want to recreate (the required part of) 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 `pkg:sysand/sensmetry/detect` 1.3.0-dev

Package the project

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 the Sysand Index or otherwise). The .kpar file can be built by running:

$ sysand build
    Building kpar `/path/to/my-project/output/my_project-0.0.1.kpar`
updating file metadata (1/1)
$ ls output/
my_project-0.0.1.kpar

Note that the hyphen in the project name becomes an underscore in the .kpar filename.

Sysand CLI creates a new directory output and puts the generated .kpar file there.

Next steps

You now have a packaged project ready for sharing. To publish it on the Sysand Index, follow Publishing your first project. To share it within a team without publishing publicly, see Host a private index.