Docs/Tools

Creating a package

Structure, test, version, and publish a Valk package.

On this page

A Valk package is a directory with a valk.json file and a src/ folder, published as a Git repository with version tags. No registry upload step is required for vman to install it, and listing the repository on vpkg.dev makes it searchable.

Directory layout#

Give the package its own repository with src/, tests/, and an optional example/:

Text
myformatter/
├── valk.json
├── src/
│   └── bytes.valk
├── tests/
│   ├── valk.json
│   └── basics.valk
└── example/
    ├── valk.json
    └── main.valk

Put your library sources in src/. Subdirectories under src/ automatically become sub-namespaces: src/text/wrap.valk is imported as use myformatter.text.

Package configuration (valk.json)#

The root valk.json declares the package's import name, the compiler version used during development, and the lowest compiler version callers need:

JSON
{
    "name": "myformatter",
    "use": "0.8.10",
    "require": {
        "valk": {
            "min": "0.8.10"
        }
    }
}
  • name is the default namespace callers import (use myformatter). It must be a valid identifier (letters, digits, underscores); when omitted, vman falls back to the repository name.
  • use pins the compiler version for contributors running vman use.
  • require.valk.min sets the lowest Valk version this package supports. When someone runs vman install, vman automatically picks the newest tag whose minimum compiler version matches their project.

If your package depends on other packages, install them with vman install from the package root. vman records them under dependencies in valk.json, and installs them transitively when someone installs your package.

Public API and visibility#

Only declarations marked with + are visible to callers that import your package. Unmarked declarations are shared across files inside your package, - restricts a declaration to its own file, and ~ makes a property readable outside its file without allowing writes:

Valk
/// Formats a byte count as a readable string, such as `"1.5 KB"`.
+ fn format_bytes(bytes: uint) String {
    if bytes < 1024 : return "%{bytes} B"
    if bytes < 1024 * 1024 : return format_unit(bytes, 1024.0, "KB")
    return format_unit(bytes, 1024.0 * 1024.0, "MB")
}

fn format_unit(bytes: uint, divisor: f64, unit: String) String {
    let value = bytes.to(f64) / divisor
    return "%{value:.1f} %{unit}"
}

Write /// documentation comments on public types, functions, methods, and properties. Generate standalone API documentation from the package root with:

Terminal
valk doc . -o docs/api.md --markdown --no-private

Tests and examples#

Give tests/ and example/ their own valk.json that points to the parent directory as a local dependency. That way your tests import the package exactly the way an external caller does (use myformatter), verifying your + visibility boundaries:

JSON
{
    "src": ".",
    "dependencies": {
        "myformatter": {
            "src": "../"
        }
    }
}

Then write tests in tests/basics.valk (avoid naming a test file after the package itself, since tests/myformatter.valk would shadow the myformatter dependency):

Valk
use myformatter

test "format_bytes formats bytes, kilobytes, and megabytes" {
    assert(myformatter.format_bytes(512) == "512 B")
    assert(myformatter.format_bytes(1536) == "1.5 KB")
    assert(myformatter.format_bytes(2 * 1024 * 1024) == "2.0 MB")
}

Run tests and check for warnings from the package root:

Terminal
valk build ./src --lint --deny-warnings
valk build ./tests --test --run
valk build ./example --run

Versioning and publishing#

vman resolves package versions from Git tags using three-part version numbers (major.minor.patch, without a leading v):

Terminal
git add -A
git commit -m "Initial release"
git tag 0.1.0
git push origin main --tags

Once pushed, anyone can install the package directly from its repository URL:

Terminal
vman install github.com/you/myformatter

vman clones the repository, picks the newest compatible tag, copies the files into vendor/, and records both the version and commit hash in the caller's valk.json so installs stay reproducible.

To make the package discoverable by search and track each version's minimum Valk requirement, list it on vpkg.dev:

  1. Create an account and log in at vpkg.dev.
  2. Open your Account page, paste the GitHub repository URL under Add package, and submit.
  3. Confirm ownership if prompted. Every tag is listed as a version automatically.

Continuous integration#

Add .gitignore entries for vendor/, tests/vendor/, example/vendor/, and debug/, and run linting, tests, and doc checks in CI:

Text
name: ci
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install vman and valk
        run: |
          curl -fL -o vman.tar.gz https://files.valk-cdn.dev/releases/vman/vman-linux-x64.tar.gz
          mkdir -p "$HOME/vman"
          tar -xf vman.tar.gz -C "$HOME/vman"
          echo "$HOME/vman/bin" >> "$GITHUB_PATH"
          echo "$HOME/.vman/bin" >> "$GITHUB_PATH"
          "$HOME/vman/bin/vman" use 0.8.10
      - run: valk build ./src --lint --deny-warnings
      - run: valk build ./tests --test --run

If your package has dependencies in valk.json, add a vman install step before building.