Projects and Workspaces

Two Questions That Sound Alike

In Chapter 4, you organized model elements into packages and made names visible across package boundaries with import. In Chapter 14, you saw that a large share of the language’s meaning lives in standard libraries your model draws on. Both chapters kept quiet about a practical question: when you write import BeverageTypes::*, how does a tool know where BeverageTypes lives – which file, which directory, which version?

The honest answer is that these are two different questions, and only one of them belongs to SysML v2.

• “What does this name mean here?” is a language question. KerML defines name resolution precisely: resolution starts in the local namespace and searches outward through containing namespaces (KerML §7.2.5.1), and import makes another namespace’s visible members available under shorter names (KerML §7.2.5.4). Every conformant tool must answer this question the same way.
• “Which files and projects should be loaded so those names exist at all?” is a tooling question. The specification defines resolution over the elements a tool has loaded; it does not say how the tool decides what to load. Manifests, dependency declarations, version pins, lock files, and workspace layouts are each tool’s own answer, and they differ between tools.

Keep the two apart and this chapter is short. An import is part of your model and travels with it. A dependency declaration is part of your project setup and does not.

import Is Language; a Dependency Is Not

Here is the boundary in one example. The model side is SysML v2 and means the same thing in every conformant tool:

package BeverageTypes {
    item def Water;
    item def CoffeeBeans;
}

package CoffeeParts {
    private import BeverageTypes::*;

    part def WaterTank {
        item water : Water;
    }
}

The import says: inside CoffeeParts, the visible members of BeverageTypes may be used by their unqualified names. It says nothing about disk layout. BeverageTypes could be in the same file, another file, another project, or an archive fetched from a server – the import is equally correct in all four cases, and equally meaningless if no loaded element provides the name.

The project side, by contrast, lives in a tool manifest. In sysml-rs it looks like this:

[dependencies]
beverage-types = { path = "../beverage-types" }

That line is not SysML v2. It is an instruction to one particular toolchain about where to find another project so that its packages become loadable. Another SysML v2 tool will express the same intent with a different file, or a repository configuration, or an IDE project – and your model’s import lines do not change when it does.

The practical rule: if removing a line changes what your model means, it is language. If removing it changes what your tool can find, it is tooling.

Projects, Commits, and Interchange

The language stops at name resolution, but OMG does standardize two things above the level of a single file, and both are worth knowing at concept level.

Projects and commits. The SysML v2 specification suite includes a standard API for model repositories, organized around a small set of concepts: a project is a top-level container for a model, a branch is a named line of development within it, and a commit is an immutable snapshot of the model at a point in time. These are interchange notions – they let two tools talk about “the same model at the same version” without sharing an implementation. Appendix C covers the API surface itself.

Interchange artifacts. As Chapter 1 noted, model interchange is normative: a project travels as a .kpar archive, and the textual files inside it use the .sysml extension. A .kpar bundles the project’s source files with a .project.json manifest that records the project’s identity and the libraries and projects it uses. These are artifacts tools produce and consume so that models can cross tool boundaries; in day-to-day modelling you author .sysml files and let your toolchain generate the interchange form when you publish.

That is the whole standardized story: names resolve by KerML’s rules, projects and commits identify model versions, and .kpar carries a project between tools. Everything else – how dependencies are declared, how versions are pinned and cached, how several projects are grouped into a workspace – is toolchain territory.

Working with Projects in sysml-rs

sysml-rs tooling – documented on the portal. Project and workspace mechanics in sysml-rs are product documentation, not language, and their canonical home is the sysml-rs documentation portal. Start there for the current behaviour; the pages below are kept up to date with the tool.

• Imports vs. dependencies – the boundary above, from the tool’s side.
• The sysml.toml manifest – project identity, editions, and standard-library selection.
• Declaring dependencies – path, git, KPAR, and registry dependencies; sysml add / sysml remove.
• Lock files and the cache – sysml.lock, reproducible resolution, and what to commit.
• Workspaces – grouping several projects and how the tool actually discovers and loads them.
• KPAR packaging – building a .kpar archive for interchange with sysml package.

What Travels and What Does Not

Every construct in the previous fourteen chapters is SysML v2 and travels with your model. The way this toolchain names, versions, and locates projects does not travel – another SysML v2 tool answers the same needs differently. What does carry across tools is the concept layer: KerML’s name-resolution rules, the project/commit vocabulary, and the .kpar interchange form. Learn the concepts here; look up the mechanics on the portal for whichever tool you are using.

Chapter 16 is the last one, and it asks what it means for a model like this to run – what a run is, how a state machine advances, and where a continuous ODE fits alongside discrete behaviour.