Modules, Packages & Tooling

Stage-0 has a minimal file import mechanism. The full module system, package manager, and unified toolchain are planned in design/MODULES_AND_PACKAGES.md.

1. Current file imports

The runnable example imports another Vela source file by path. The source comment says the imported file's top-level definitions are run once, and the path is relative to the working directory.

# Source: .sources/vela/examples/modules_demo.vela
use "lib/greet.vela"

print(greet("Vela"))
print(shout("modules work"))
print(f"PI is about {PI}")

This is not the final package/module design. It is a seed feature for multi-file examples.

2. Planned module paths

The design spec proposes filesystem-driven modules:

• src/lib.vela as a library root,
• src/main.vela as a binary root,
• foo.vela as module foo,
• foo/mod.vela as a directory module root,
• dotted module paths such as my_pkg.data.clean.

It also proposes use forms for modules, named imports, aliases, relative imports, and re-exports.

3. Planned visibility

The planned visibility model is:

• private by default,
• pub for exported API,
• pub(crate) for package-internal API,
• pub use for curated public surfaces.

This is design-stage behavior, not Stage-0 seed behavior.

4. Planned package files

The proposed package ecosystem uses:

• Vela.toml as the manifest,
• Vela.lock as a content-addressed lockfile,
• mandatory namespaces for published packages,
• Vela-toolchain.toml for toolchain pinning,
• a registry named Constellation.

The design emphasizes reproducibility: pinned toolchains, deterministic builds, content hashes, offline vendoring, and semver checks based on public API diffs.

5. Current CLI surface shown by examples

The examples use vela run, command-line arguments via global ARGV, and single-file scripts.

# Source: .sources/vela/examples/args.vela
if ARGV.len == 0:
    print("no arguments given.  try:  vela run examples/args.vela Alice Bob")
else:
    print("got", ARGV.len, "argument(s):")
    for name in ARGV:
        print("  hello,", name)

6. Planned tooling

The design proposes a single vela binary with commands such as:

• vela new, vela init, vela build, vela run,
• vela test, vela fmt, vela lint, vela bench,
• vela repl, vela doc, vela check,
• vela add, vela remove, vela update, vela publish,
• vela vendor, vela clean,
• vela lsp, and a Jupyter kernel.

Until those exist in the implementation, document them as planned.