SLM - Stanza Library Manager

Stanza has a library manager called "Stanza Library Manager" or SLM for short. SLM is used to manage the dependencies for your JITX project. This include:

The JITX Runtime and tracking compatibility as upgrades are made.
The JITX standard libraries like OCDB
Any third-party or user specific libraries that you choose to integrate into your project.

With SLM we can keep all of our code synchronized and use the latest features from the JITX environment.

How does SLM work?

SLM consists of two parts:

The slm command-line executable that manages dependencies
The slm.toml configuration file that is present in any SLM capable projects.

Your interface to SLM will primarily be through the slm.toml configuration file in your project. This file will typically look like:

name = "motor-controller"
version = "0.1.0"
[dependencies]
JITX = { path = "{SLM_ROOT}/JITX" }
ocdb = { path = "{SLM_ROOT}/ocdb" }

Notice that these are the default dependencies that JITX adds by default. These are path dependencies and reference folders on your local computer's disk. Paths will use forward slash on all platforms.

Adding Dependencies

The easiest way to add dependencies to your JITX project is by using the slm command line utility. In your JITX VSCode project, start by opening a terminal with Terminal -> New Terminal. In the created terminal, you can run:

$>  $SLM add -git StanzaOrg/maybe-utils
$>  $SLM clean

This would grab the latest tagged version of maybe-utils from Github and add it to your local motor-controller/slm.toml configuration file. This method requires git on your $PATH (or on Windows %PATH% or in Powershell $env:PATH).

The clean command is a tool to tell slm that the dependency expectations have changed.

IMPORTANT - After adding dependencies, it is a good idea to kill the JITX stanza terminal and re-run the design with ctl-enter. Otherwise, the new dependencies will not be downloaded.

How are dependencies added?

The previous add command would result in the following slm.toml file:

name = "motor-controller"
version = "0.1.0"
[dependencies]
JITX = { path = "{SLM_ROOT}/JITX" }
ocdb = { path = "{SLM_ROOT}/ocdb" }
maybe-utils = { git = "StanzaOrg/maybe-utils", version = "0.1.4" }

This will pull in the maybe-utils library and make it available for your project's code to use.

Ideally - you would never modify the slm.toml file directly.

Adding Dependency By Path

You can alternatively add a dependency by path:

$>  $SLM add -path ~/src/my-library
$>  $SLM clean

This would add a my-library dependency to the slm.toml file that references the ~/src/my-library path directly. The my-library directory must contain a valid SLM project including a ~/src/my-library/slm.toml file.

There are additional options to customize this behavior. See $SLM -h for more info.

IMPORTANT - After adding dependencies, it is a good idea to kill the JITX stanza terminal and re-run the design with ctl-enter. Otherwise, the new dependencies will not be downloaded.

Setting up Git

To add dependencies from Github, you will need ssh and git on your path. In addition, you will need to have setup an SSH key for your github account so that you can clone repositories.

To check that this is working correctly, run:

ssh -T git@github.com
Hi <user>! You've successfully authenticated, but GitHub does not provide shell access.

Setup HTTPS mode:

If all else fails and you , try setting the SLM_PROTOCOL environment variable before launching VSCode:

$>  cd motor-controller
$>  export SLM_PROTOCOL="https"
$>  code .

Tips for SLM on Windows

The environment variable syntax in powershell is a little different from Linux and Mac OS-X. The SLM environment variable is accessed with $env:SLM. In addition, to launch $env:SLM as an executable you will need to use a & character prefix in powershell.

Example:

$> cd motor-controller
$> &$env:SLM add -git StanzaOrg/maybe-utils
$> &$env:SLM clean

Want to know more about SLM ?

Try running:

# Mac/Linux:
$SLM help
# Windows:
&$env:SLM help

Or review the code on Github: StanzaOrg/slm

Upgrading Legacy Projects

Projects created before JITX version 2.30 will likely have been created without the SLM configuration files. To upgrade your project and use SLM for managing dependencies moving forward, you will need to run a JITX command from the VSCode command palette. Here are the steps:

Open the JITX project in VSCode that you wish to upgrade.
Press ctl + shift + P to launch the command pallete.
Type JITX: Upgrade Legacy Project to SLM and this should filter to a command option.
Press ENTER and the command will convert the projects present in the current workspace.

This new configuration will leave the code in your project as is, but it will update the dependencies. JITX-provided dependencies such as OCDB that your project probably uses will be upgraded to new versions.

This means that the open-components-database directory will still exist but the SLM dependencies will no longer reference it. Assuming you have not made any local changes to the open-components-database directory in your project - it is safe to remove the open-components-database folder.

If you are converting an older project, you may find your project won't compile anymore. You will likely need to make some updates to work with the latest version of OCDB. Don't hesitate to reach out if you run into trouble.

JITX Documentation