Importing published libraries

In SysON, published libraries may be imported by projects.

To do so, use the dedicated command from the omnibox

Import published library command

This command is available for any project, to import any library.

Upon selecting this command, a dialog prompts for the libraries to import.

Import published library command dialog

The import is done either by reference or by copy. With the former, a dependency is added from the project to the library, and the contents of the library are accessed in read-only mode. With the latter, a copy of the contents of the library are copied into the project, and they may be used and edited as if they had been manually created into the project. There is no link between the copied contents and the original library contents so there is no way to "re-synchronize" these contents (e.g. in case the library has a new version).

Import published library command dialog

Upon importing:

  • If one of the selected libraries is already imported (same namespace, name and version) then it will not be imported a second time.

  • Dependencies are re-loaded, which may trigger imported libraries to re-appear in the Explorer view if they had been manually removed.

Upon a successful import, a notification appears in the bottom right corner.

Import published library command success notification

The project contents are updated.

Project contents after successfully importing a published library

If a document from an imported-by-reference library has a root element that is an instance of LibraryPackage, then that document is displayed under the 'User libraries' node in the 'Explorer' view.

Imported published library under User libraries

1. Updating the version of a library dependency

The version of a published library used by a project may be updated. Since publish library versions are strings, there is no natural order on the versions of libraries. This means library versions have no particular "semantic meaning", so updating from one version to another version of a library may have very large or very small impacts. This is totally up to the library authors.

Only libraries that have been imported-by-reference may be updated. Libraries imported-by-copy have no link to their originating library, and may not be updated automatically.

To update a library, select in the Explorer view, a document from an imported-by-reference published library. These documents may be located at the root of the project, or under node Libraries > User libraries.

Open the contextual menu to find the 'Update library' action.

Contextual menu action 'Update library' for documents from imported-by-reference published libraries

Upon selecting this action, a dialog prompts for the new version of the library to use.

Dialog for the 'Update library' action

After the library update has been performed, if successful, a notification appears.

Dialog for the 'Update library' action

Updating a library means that the contents of the project are modified, possibly breaking some aspects of the project, so validation errors may occur as a consequence. Libraries may add, remove or edit their contents freely between versions, so there is no guarantees that two versions of a library are compatible or even somewhat resembling. This means projects may become invalid because some of the library elements it was built upon no longer exist, or their identity has changed.

Library authors should note that the identity of a document is based on its namespace (ID of the authoring project from which the library is published) and its name. Renaming a document may thus result in breakages in cross-document references.