Project command

Creates SysML v2 and KerML projects and manages the projects they use. A project is a directory with a .project.json and .meta.json files that describe it, give its version and list its usages, that is, other projects it depends on. The command is based on the Sysand package manager and writes the same files Sysand does. For now we make no compatibility promises between projects managed by this command and Sysand.

Command	Description
init	Create a project
add	Add a usage to the current project, update the lockfile and install the locked projects
lock	Resolve the current project’s usages and write them to the lockfile
sync	Install the projects in the lockfile

add, lock and sync act on the current project: the nearest of the current directory and its parent directories that contains .project.json.

The files the commands work with are:

File	Contents
`.project.json`	The project’s name, publisher, version, license and usages
`.meta.json`	When the project was created, its metamodel, and the packages its model files define
`sysand-lock.toml`	Lockfile. It records the exact version, and where it comes from, of every project the current project uses, directly or through other projects
`.sysand/`	Environment. Holds the installed projects recorded in the lockfile. Syside finds the libraries a project uses here
`sysand.toml`	The project’s configuration

SysML v2 and KerML standard libraries are not locked or installed, because Syside provides them.

Init command

Creates a project in a directory, creating the directory if it does not exist.

syside project init [PATH] --publisher <PUBLISHER> --metamodel <KIND> --kind <KIND> [options]

[PATH] - the directory to create the project in. Defaults to the current directory

Option	Description
`--publisher <PUBLISHER>`	Required. The person, team or organization that develops the project. Together with the name, it identifies the project when other projects use it
`--metamodel <KIND>`	Required. The metamodel the project is written in: `sysml` for SysML v2 or `kerml` for KerML. Its current release is recorded in `.meta.json`
`--kind <KIND>`	Required. The kind of project to create. `project-json`, currently the only kind, is a directory with `.project.json` and `.meta.json`
`--name <NAME>`	The name of the project. Defaults to the name of the directory
`--version <VERSION>`	The version of the project, in Semantic Versioning 2.0 format. Defaults to `0.0.1`
`--license <LICENSE>`	The license of the project, as an SPDX license expression such as `MIT OR Apache-2.0`. Defaults to declaring no license

The command also takes the global options.

For example, to create a project for the Drone model in a new drone directory:

syside project init drone --publisher "Acme Labs" --name Drone --version 0.1.0 \
    --metamodel sysml --kind project-json

Add command

Adds a usage of another project to the current project’s .project.json, then updates the lockfile and installs the locked projects into .sysand, as sync does. If locking or installing fails, .project.json is left as it was.

syside project add <PUBLISHER/NAME> --version-constraint <CONSTRAINT> [options]

<PUBLISHER/NAME> - the publisher and the name of the project to use, separated by /. Spell them as the project does, such as "Acme Labs/My Lib", or in lowercase with - for spaces, such as acme-labs/my-lib

If the current project already uses that project, its version constraint is replaced.

Option	Description
`--version-constraint <CONSTRAINT>`	Required. The versions of the used project to allow, assuming it uses Semantic Versioning. The syntax is that of Rust’s Cargo, shown below

The command also takes the resolution options and the global options.

The version constraints are:

Constraint	Allows
`1.2.3` or `^1.2.3`	Any version compatible with 1.2.3: at least 1.2.3, and below 2.0.0
`=1.2.3`	Exactly 1.2.3
`<2`, `>=3`	Any version below 2, or any version from 3 on
`>=1.2, <1.5`	Any version that satisfies both
`*`	Any version, excluding prereleases

For example, to use any 1.x version of acme-labs/widgets:

syside project add acme-labs/widgets --version-constraint ^1

The report generation example shows a model that uses the SysideViews library from the Sysand index.

Lock command

Resolves the current project’s usages, and the usages of the projects they name in turn, to exact versions, and writes them to sysand-lock.toml. It does not install them, use sync afterwards to do that.

syside project lock [options]

The command takes the resolution options and the global options.

Sync command

Installs the projects in the current project’s lockfile into .sysand, creating .sysand if it does not exist, and removes the projects the lockfile no longer lists. Without a lockfile, it locks first.

Run it after cloning a project that has a lockfile, or after the lockfile changes.

syside project sync [options]

The command takes the resolution options and the global options.

Resolution options

add, lock and sync find projects in indexes. The default index is https://sysand.com.

Option	Description
`--index <URL>`	An index to search before the default ones. Repeat the option, or separate URLs with commas, to give several. Defaults to the `SYSAND_INDEX` environment variable
`--default-index <URL>`	An index to use instead of the default index. Repeat the option, or separate URLs with commas, to give several. Defaults to the `SYSAND_DEFAULT_INDEX` environment variable
`--no-index`	Do not use any index. Cannot be combined with `--index` or `--default-index`

Global options

Option	Description
`--help`	Display the help message of the command
`--verbose`	Use verbose output
`--quiet`	Do not output log messages. Cannot be combined with `--verbose`
`--no-config`	Do not read `sysand.toml` from your configuration directory or the project. Also turned on by the `SYSAND_NO_CONFIG` environment variable
`--config-file <PATH>`	Also read the configuration file at `PATH`. Defaults to the `SYSAND_CONFIG_FILE` environment variable

Configuration

Warning

Coming soon. Configuration file locations, their precedence, merging and supported options are currently unstable and will change in the future.

Authentication

An index that needs credentials is authenticated with the credentials stored in the operating system’s credential store by Sysand’s sysand auth login, and with credentials given in environment variables. Each set of credentials has a label, <LABEL>, of your choosing:

Environment variable	Contents
`SYSAND_CRED_<LABEL>`	The URLs the credentials are for, as a glob pattern such as `https://index.example.com/**`
`SYSAND_CRED_<LABEL>_BEARER_TOKEN`	A bearer token
`SYSAND_CRED_<LABEL>_BASIC_USER`, `SYSAND_CRED_<LABEL>_BASIC_PASS`	The name and the password to authenticate with, using HTTP basic authentication

Environment variables

Variable	Effect
`SYSAND_INDEX`	Comma-separated indexes to search before the default ones, when `--index` is not given
`SYSAND_DEFAULT_INDEX`	Comma-separated indexes to use instead of the default index, when `--default-index` is not given
`SYSAND_NO_CONFIG`	When set to anything other than an empty value, `0`, `false`, `no`, `off`, `f` or `n`, the same as `--no-config`
`SYSAND_CONFIG_FILE`	The same as `--config-file`
`SYSAND_CRED_<LABEL>...`	Credentials for indexes: see Authentication

Exit codes

Code	Meaning
`0`	The command succeeded
`1`	The command failed, for example because the current directory is not inside a project or no compatible set of versions exists
`2`	The command line is not valid, for example because an option is unknown

Python API

The project module offers the commands as functions:

Function	Description
`project.init`	`init`. Unlike the command, it requires `name` and `version`. `kind` takes a `project.ProjectKind`, such as `ProjectKind.PROJECT_JSON`
`project.add`	`add` command, for the project in `project_dir`. Publisher and name of the project to use are separate arguments
`project.lock`	`lock` command, for the project at `path`, which defaults to the current directory
`project.sync`	`sync` command, for the project at `path`, which defaults to the current directory

The functions take their arguments as keywords only. They read the same environment variables, credentials and configuration files as the commands.

import syside.project

syside.project.init(
    project_dir="drone",
    name="Drone",
    publisher="Acme Labs",
    version="0.1.0",
    metamodel="sysml",
    kind=syside.project.ProjectKind.PROJECT_JSON,
    license="MIT",
)
syside.project.add(
    project_dir="drone",
    publisher="acme-labs",
    name="widgets",
    version_constraint="^1",
)