The workspace manifest

What picklescript.toml does today, and what it reserves for the future.

vlatest

The manifest is named picklescript.toml.

What the loader reads today

Exactly one table has an effect: [workspace] members.

# PickleScript workspace manifest.

[workspace]
members = [
    { name = "compiler", path = "compiler" },
    { name = "cli", path = "cli" },
    { name = "runtime", path = "runtime" },
    { name = "std", path = "stdlib" },
]

A member's name becomes a crate name in the module namespace. When an import starts with that name, resolution happens inside the member's directory and no other location is searched, a crate name is authoritative.

That is how std.json finds stdlib/json.pkl: std is a workspace member that points at stdlib, so the remaining segment json is resolved to stdlib/json.pkl.

A single-segment import of a crate name maps to lib.pkl or main.pkl in that crate's directory.

The rest of the file is a plan, not a feature

The shipped manifest carries several further tables. None of them affect compilation today; they describe the layout a future package manager will use.

[package]
name = "picklescript"
version = "0.1.0"
description = "The PickleScript language toolchain."
authors = ["PickleScript team"]
license = "MIT"

# Where the package manager keeps its state.
[paths]
packages = ".pickle/packages"
cache = ".pickle/cache"
registry = ".pickle/registry"

# Default registry for `author/package` dependency names.
[registry]
default = "pickle"

These tables reserve the layout a package manager will use. The one key the compiler reads today is [workspace] members, the list of directories it searches for modules. The rest are accepted and ignored, so you can write them ahead of time.

Module resolution without a manifest

When the first segment of an import does not match a workspace member, the loader falls back to a filesystem search. It tries, in order:

  1. The directory of the importing file.
  2. Each ancestor of that directory, up to and including the process working directory.
  3. <cwd>/src/.

Each base is tried as a module file (<segments>.pkl) and then as a package directory (<segments>/).

That is how a sibling file resolves:

project/
    main.pkl
    helper.pkl
import { greet } from helper

fn main() {
    println(greet("ada"))
}

helper resolves to helper.pkl in the importing file's directory. See Modules and imports for the full rules.

Next steps