Package Manager (vslpkg)

vslpkg is the Visuall package manager. Declare dependencies in vsl.toml, install with vslpkg install, and the compiler reads vsl.lock to resolve imports.

Package Store Layout

Creating a Package

cd my-project
vslpkg init my-project

This creates a vsl.toml scaffold:

[package]
name        = "my-project"   # lowercase letters, digits, hyphens
version     = "0.1.0"        # semver: MAJOR.MINOR.PATCH
description = ""
license     = ""             # SPDX identifier, e.g. "MIT"

[dependencies]
# alias = { git = "https://github.com/user/repo", version = "1.0.0" }
# alias = { path = "../local-lib" }

Declaring Dependencies

Two types of dependencies:

Git Dependency

Fetched from a remote Git repository at a specific tag (v<version>):

[dependencies]
mathlib = { git = "https://github.com/alice/mathlib", version = "1.0.0" }
utils   = { git = "https://github.com/bob/vsl-utils",  version = "2.3.1" }

Path Dependency

Points to a local directory with its own vsl.toml:

[dependencies]
mathlib = { path = "../mathlib" }
shared  = { path = "./vendor/shared" }

Installing Dependencies

vslpkg install

This resolves all transitive Git dependencies using Minimal Version Selection (MVS), clones each into the local cache, and writes vsl.lock.

To re-download and overwrite: vslpkg install --force

The Lockfile

After install, vsl.lock is written. Commit this to version control for reproducible builds.

# vsl.lock - generated by vslpkg - do not edit manually

[[package]]
alias   = "mathlib"
url     = "https://github.com/alice/mathlib"
version = "1.0.0"
dir     = "/home/alice/.visuall/packages/mathlib@1.0.0"

[[package]]
alias   = "utils"
dir     = "/home/alice/projects/vendor/utils"

Compiling with Packages

When vsl.lock exists in the same directory as your source (or its parent), visuallc loads it automatically. No extra flags needed:

visuallc main.vsl -o main

Publishing a Package

vslpkg fetches directly from Git. No central registry. To publish:

1. Create a Git repo with your .vsl files and a vsl.toml at the root
2. Tag a release: git tag v1.0.0 && git push origin v1.0.0
3. Users add it to their vsl.toml

Required Repository Layout

mylib/
├── vsl.toml          # required: must be at the repository root
├── mylib.vsl         # your module source
└── ...

Versioning

MVS selects the highest minimum version across all consumers, so breaking changes (major bumps) are not automatically adopted by dependents.