Lab 03a - Using VoltScript Dependency Management for VSEs and VSS Libraries

Duration 20 min

What you will learn

You'll learn how to use dependency management, how it creates a seti.ini, and how to use UseVSE to include the VoltScript Extensions.

Prerequisites

Lab 02 completed

Steps

The IDE

Create a new VS Code VoltScript Workspace folder called lab-03.
1. Open Visual Studio Code.
2. From the Explorer view, click Open Folder.
3. Create a new folder in your user directory, with the name stated above.
4. Select the newly created folder to open in VS Code.

atlas.json

Create a new atlas.json file:

Note

The atlas.json file is the VoltScript equivalent of Node.js's package.json, Maven's pom.xml or Rust's cargo.toml. It defines metadata about your project (name, version, authors, license), dependencies, structure, and scripts.
1. Right-click in the empty pane and select New File from the context menu.
2. Name the file atlas.json.
3. Type an opening curly brace "{" and press enter. VS Code automatically adds the closing curly brace "}".
4. If the PROBLEMS view isn't visible, select View → Problems. Note the validation errors, which will identify any required properties which are missing.
Set name to "lab03".
Set version to "1.0.0".
Set description to "Lab Number 3".
Add the authors array. Add an array element with your name.
Set sourceDir as "src".
Set testDir as "test".
Set mainScripts as "main.vss".
Set libsDir as "libs".
Set vsesDir as "vses".
Add repositories array.
1. Add a JSON object. Required properties for it will appear in the Problems view.
2. Set id to "volt-mx-marketplace".
3. Set type to "marketplace".
4. Set url to "https://community.demo-hclvoltmx.com/marketplace".
5. Add another JSON object. Required properties for it will appear in the Problems view.
6. Set id to "hcl-github".
7. Set type to "github".
8. Set url to "https://api.github.com/repos/hcl-tech-software".
Add dependencies array. Add a JSON object. Required properties for it will appear in the Problems view.
1. Set library to "voltscript-testing".
2. Set version to "1.0.1".
3. Set module to "VoltScriptTesting.vss".
4. Set repository to "hcl-github".
Add another JSON object to the dependencies array.
1. Set library to "voltscript-json-converter".
2. Set version to "latest".
3. Set module to "VoltScriptJsonConverter.vss".
4. Set repository to "hcl-github".
Add vseDependencies object. This is an object, because each element needs a label that will be used in the UseVSE statement.
Add a label "StreamVSE". For the value, then add an empty JSON object.
1. Set library to "StreamVSE VoltScript Extension".
2. Set version to "1.0.4".
3. Set module to "streamvse".
4. Set repository to "volt-mx-marketplace".
Save the atlas.json. The final atlas.json should look like this:

{
    "name": "lab03",
    "version": "1.0.0",
    "description": "Lab Number 3",
    "authors": ["YOUR_NAME"],
    "sourceDir": "src",
    "testDir": "test",
    "mainScripts": [
        "main.vss"
    ],
    "libsDir": "libs",
    "vsesDir": "vses", 
    "repositories": [
        {
            "id": "volt-mx-marketplace",
            "type": "marketplace",
            "url": "https://community.demo-hclvoltmx.com/marketplace"
        },
        {
            "id": "hcl-github",
            "type": "github",
            "url": "https://api.github.com/repos/hcl-tech-software"
        }
    ], 
    "dependencies": [
        {
            "library": "voltscript-testing",
            "version": "1.0.1",
            "module": "VoltScriptTesting.vss",
            "repository": "hcl-github"
        },
        {
            "library": "voltscript-json-converter",
            "version": "latest",
            "module": "VoltScriptJsonConverter.vss",
            "repository": "hcl-github"
        }
    ], 
    "vseDependencies": {
        "StreamVSE": {
            "library": "StreamVSE VoltScript Extension",
            "version": "1.0.4",
            "module": "streamvse",
            "repository": "volt-mx-marketplace"
        }
    }
}

Info

VoltScript dependencies are, as with other dependency management systems, downloaded into a local repository in your user directory. For Maven, it is .m2, for Rust, it is .cargo, and for VoltScript, it is .vss.
This allows dependencies to be built from local artifacts whenever possible, rather than pulling from remote locations. You can restrict which platform's VSE files get built into your product by using the runtimePlatforms element in atlas.json. For more details, see How to Structure an atlas.json.

From the Command Palette in VS Code, run "VoltScript: Run Dependency Setup".
This will ensure that (among other things) a .vss folder is created within your VoltScript workspace.

atlas-settings.json

Within the .vss directory, an atlas-settings.json file holds a single JSON object containing other JSON objects, whose labels match the repositories listed in the atlas.json file. Each of these objects specify the type and necessary authentication credentials for the repository.

For github types, this is a Personal Access Token.
For webserver types, there are two options:
- Unauthenticated / Open Web Servers: the credentials should be an empty string.
- Authenticated / Controlled Access : the credentials should be a Base64 encoded username and password.
For marketplace types, this is a username and password.

Info

While this authentication information can be hard-coded directly into the atlas-settings.json file, VoltScipt Dependency Manager respects security concerns about having this hard-coded information accessible. Therefore, if this information is stored in the format of "${env.FOO}", the VoltScript Dependency Manager will retrieve the information from the appropriate environment variable (for this example "FOO").

Warning

There is no intention to support retrieving credentials from credential stores.

Create a text file called atlas-settings.json in your .vss directory:
Note

WINDOWS ONLY
1. In Windows Explorer or a terminal, navigate to your user directory and open the .vss directory.
2. Select File > New File... from the VS Code Menu, and give it the name atlas-settings.json. The new file should open in your VS Code editor.
Mac / Linux Dev Container ONLY
1. From the VS Code Terminal (if necessary, open one by selecting Terminal > New Terminal from the VS Code Menu), type in the command:
```
touch ~/.vss/atlas-settings.json
```
2. Select File > Open... from the VS Code Menu, type:
```
~/.vss/atlas-settings.json
```
  then click the OK button.
After the file opens in your VS Code editor, create an empty JSON object.

Info

Unlike the atlas.json, you will not immediately get content assistance. The atlas-settings.json file defines a a JSON object which contains JSON objects for each repository, each with a label. So you will need to add a label whose value is a JSON object, and that JSON object will provide content assistance. Alternatively, there are snippets available by typing atlas-settings which will generate JSON objects with all possible options.
Add a label "hcl-github". For its value, create a JSON object. Required properties for it will appear in the Problems view.
Set type to "github".
Set token to your GitHub Personal Access Token.

If you don't have one yet, follow GitHub's documentation for creating a GitHub Personal Access Token. The value will begin "ghp_". For more details see how-to guide.
Create another JSON object with the label of "volt-mx-marketplace".
Set type to "marketplace".
Set authUrl to "https://accounts.auth.demo-hclvoltmx.net/login".

Set username and password to your credentials for Volt MX Marketplace.

You can create an account or check your login credentials at Volt MX Marketplace. If you are creating a new account, make sure to successfully log in to activate the account before using the credentials in dependency management.

A sample atlas-settings file sould look something like this:

{
    "hcl-github": {
        "type": "github",
        "token": "${env.TOKEN}"
    },
    "my-web-server": {
        "type": "webserver",
        "credentials": "${env.CRED}"
    },
    "volt-mx-marketplace": {
        "type": "marketplace",
        "username": "${env.USERNAME}",
        "password": "${env.PASSWORD}",
        "authUrl": "https://accounts.auth.demo-hclvoltmx.net/login"
    }
}

Save your atlas-settings.json file.

VoltScript Dependency Manager

Info

VoltScript Dependency Manager can use any of three repository types, as defined in the atlas-settings.json file. These types are:

github A GitHub repository requires a Personal Access Token, associated with the "token" element from the atlas-settings object.
webserver A Web Server repository requires Base64 encoded credentials, which are specified in the credentials element.
marketplace A specialized form of Web Server repository, the Marketplace is for a (usually a Volt-MX Marketplace) website that accepts a username and password. These values are passed after a secure SSL connection is made with the remote site defined in the authURL element.

The VoltScript Dependency Manager requires 4 pieces of information:

The folder for the project (your workspace folder)
The location of the atlas.json file, from which to build the dependencies.
The location of the atlas-settings.json file, from which to get the necessary authentication information for any repositories defined in atlas.json.
A boolean instruction to force reload from remote repositories in the event that local resources already exist.

Tip

When you run the VoltScript Dependency Manager, it will ask you for this information one at a time, and will preload the default answer for subsequent questions using the information from your answers. If you do not answer quickly enough, it will timeout and proceed to the next question. Therefore it is a good idea to copy your VoltScript workspace filepath to your clipboard (the first question) before proceeding.

Archipeligo Questions

From the Command Palette, run "VoltScript: Install Dependencies".

This will invoke VoltScript executable and instruct it to run the VoltScript Dependency Manager (archipelago.vss). Answer the questions one at a time (or just press Enter to accept the default) to proceed.

The VoltScript Dependency Manager will (depending upon your connection speed) take a few moments to complete operations. If any problems occur they will be listed in the VS Code terminal window. Nearly All problems that occur are due to either entering the directory incorrectly when prompted, or invalid / incomplete information in the atlas.json file. It is very common to make a mistake here, methodically check your JSON and VoltScript Workspace folder hierarchy if you have problems.

Success

Assuming the VoltScript Dependency Manager runs to completion, your project should now have "src", "test", "libs" and "vses" directories.

The src directory will normally be empty.
The test directory will normally empty.
The libs directory should now be populated with VoltScriptTesting.vss and VoltScriptJsonConverter.vss.
The vses directory should now be populated with dll and so files for StreamVSE and JsonVSE. JsonVSE is a downstream dependency used by VoltScript JSON Converter, and is automatically picked up because it is listed in the atlas.json for VoltScript JSON Converter.
A new file, seti.ini, has been created. This contains mappings for the VoltScript Extensions (VSEs) and will be used when processing UseVSE statements.
A new file, effective-atlas.json, has been added to the root of the directory. This contains the aggregated settings for the project.

VoltScript Dependency Manager Success

Proceed to Lab 03b - Using a VoltScript Extension to parse JSON