Skip to content

atlas.json

The atlas.json file is used to define a project's metadata as well as dependencies and the repositories in which they reside. It's intended to be included in source control for the project so it does not include any credentials for accessing repositories. For more details, see How to Structure an atlas.json. For dependency management, it's only important to reference certain elements in atlas.json:

  • repositories: an array of repository objects. The repository contains three properties:
    • id: used to cross-reference with the atlas-settings.json.
    • type: currently only "github" and "webserver" are supported.
    • url: base URL for API calls to the repository. See below for more details how this is used.
  • dependencies: an array of dependency objects mapping to VoltScript files to use. The dependency contains three properties:
    • library: the group under which the .vss files and their own atlas.json are grouped.
    • version: an explicit version number mapping to a release, or "latest" to also retrieve the most recent.
    • module: the specific file to be incorporated.
    • repository: an optional property mapping to a repository ID. If used, Archipelago will look in that repository first.
  • vseDependencies: an object of extension dependency objects mapping to extensions to use. The extension dependency is a JSON object whose label is the name you intend to use in the UseVSE statement, and which has three properties:
    • library: the group under which the VoltScript Extension(s) are grouped. For Volt MX Marketplace, this is the title of the asset as found in the breadcrumbs when manually navigating to the extension on Volt MX Marketplace. For HCL extensions, this will be the VSE name followed by " VoltScript Extension", e.g. "JsonVSE VoltScript Extension".
    • version: a human-readable version number mapping to the asset version, e.g. "1.0.1". "latest" is not relevant for Volt MX Marketplace.
    • module: the specific file to be downloaded. For Volt MX Marketplace, this is the VSE name in lowercase, e.g. "jsonvse". NOTE: This will no longer change with every release.
    • repository: an optional property mapping to a repository ID. If used, Archipelago will look in that repository first.
  • sourceDir: the directory name, relative to the root of the project, in which to store VoltScript files for main execution.
  • testDir: the directory name, relative to the root of the project, in which to store VoltScript files for running unit and integration tests.
  • vsesDir: the directory name, relative to the root of the project, in which to store VoltScript Extensions. If omitted, extensions are put in the root of the project.
  • libsDir: the directory name, relative to the root of the project, in which to store the VoltScript Library dependencies. If omitted, the VoltScript files are put in the root of the project.
  • mainScripts: an array of files that are main runnable scripts.
  • unitTestScript: an array of files that are unit test runnable scripts.
  • integrationTestScripts: an array of files that are integration test runnable scripts.
  • runtimePlatforms: an array of platforms for which to add VSEs to your project.

Note

A starter atlas.json with all options annotated can be accessed by typing atlas in an atlas.json. A starter atlas.json specific to Volt Foundry development can be accessed by typing foundry-atlas in an atlas.json. For more details, see Volt Foundry atlas.json. If you are comfortablke structuring your atlas.json, you can create uncommented minimal starters with minimal-atlas or minimal-foundry-atlas.

VSE Extensions

The library is the asset title, e.g. "JsonVSE VoltScript Extension". The module is the asset filename when downloaded, minus the file suffix, e.g. "jsonvse". The Volt MX Marketplace repository URL is "https://community.demo-hclvoltmx.com/marketplace".

Info

By default, VSE files for all platforms (Windows, Linux, MacOS) will be copied into the project. You can use runtimePlatforms property to restrict which platforms' VSEs are copied in. For more details, see How to Structure an atlas.json.

.vss Directory

Dependencies will be stored centrally in a .vss directory in the user's directory. This automatically gets created by the VS Code extension. They are divided into a subdirectory for the library, a subdirectory for the version, and the relevant module files. If the version is "latest", they are also copied to a sub-directory with the actual version number. So for VoltScript Testing Framework, this might be:

.vss
    voltscript-testing
        latest
            VoltScriptTesting.vss
            version.txt
        1.0.0
            VoltScvriptTesting.vss

For Volt MX Marketplace, the module downloads a specific version. There is no option for "latest". It downloads a main zip and extracts as platform-specific zips. For the jsonvse example earlier, the directory structure would be:

.vss
    JsonVSE VoltScript Extension
        1.0.0
            JsonVSE.zip
            JsonVSE-windows-amd64.zip
            jsonvse-linux-x86_64.zip
            jsonvse-darwin-arm64.zip

These directories are used to avoid downloading dependencies from the internet every time.