Migrate diagram views

Syside v1 draws diagrams with a newer version of the engine that syside viz used in Syside v0.11. Most views written for Syside v0.11 need no changes. Three things change:

  • the spelling of the diagram settings;

  • the syside viz and syside grid export command lines;

  • how some diagrams look.

Rename diagram settings

Settings in the [viz] table of syside.toml are now spelled in kebab-case. Replace every _ with - in the keys. Values stay as they are:

# before
[viz.filters.action_flow]
show_inherited_nodes = false

# after
[viz.filters.action-flow]
show-inherited-nodes = false

The attribute names under conditions come from your model, so they keep its spelling.

The old spelling still works in v1, with a warning. It is deprecated. When a file has both spellings of a key, the kebab-case one applies. Diagram settings lists every setting.

Update the viz and grid commands

syside viz and syside grid export no longer accept -i / --include or -e / --exclude. To migrate a command:

  1. Pass all included paths as the [paths...] argument on the command line.

  2. Move the excluded paths into exclude in the workspace’s syside.toml.

# before
syside viz view models/ --include "libraries/" --exclude "models/sandbox/**"

# after
syside viz view models/ libraries/

# after, in syside.toml
exclude = ["models/sandbox/**"]

When you pass the paths:

  • Keep them together, before or after the options. An option between two paths, as in models/ -o out libraries/, leaves the later paths unrecognized. The command exits 2.

  • Run the command from the workspace folder. syside.toml is found by walking up from the folder you run the command in.

  • Name the views with -n if the included paths declare views you don’t want. The long form is --name for syside viz and --qualified-name for syside grid export. Without it, each command takes every view it loads, as it did with -i.

You can put the included paths in include in syside.toml instead, and pass only the other paths on the command line:

# syside.toml
include = ["libraries/"]

syside viz view models/

An exclude entry in syside.toml now applies to the VS Code Extension too. Read Migrate Syside settings before you move one.

Syside v1 reports errors that Syside v0.11 didn’t (see Migrate SysML models). syside viz doesn’t draw a model with errors unless you pass --allow-errors. Even then, critical errors, such as a syntax error, stop the command, and other errors can leave a diagram incomplete or wrong where they are (see Viz command). For syside grid export, see Migrate grid views.

Review the diagrams

Tip

Draw each view again and compare it with the output of syside viz in Syside v0.11, as described in Compare the exports. Some changes can alter a diagram without any edit to the model, for example:

  • Ports and parameters count at their owner’s depth (depth explained).

  • A filter keeps an element only when its condition is true (Select view elements). A view left with nothing to draw makes syside viz exit 4.