Packages and modules

A package is a directory with a wolang.toml manifest. A module is a directory of .wo files inside it:

Last updated Invalid DateVersion 1.0.0

Layout

A package is a directory with a wolang.toml manifest. A module is a directory of .wo files inside it:

Text
mygame/
├── wolang.toml
└── src/
    ├── main.wo              module mygame
    ├── combat/
    │   ├── damage.wo        module mygame.combat
    │   └── weapons.wo       module mygame.combat
    └── engine/
        └── physics/
            └── body.wo      module mygame.engine.physics

A module's name is the package name followed by the path below the source root. Every .wo file in one directory belongs to one module; a directory with no .wo files declares no module.

Modules are directory-scoped rather than file-scoped on purpose: adding a file never requires editing a module declaration, and the layout matches how a game is already split into plugins and subsystems.

Directories whose name starts with . are tooling, not source, and are skipped — including the compiler's own .wolang-cache.

The manifest

Text
[package]
name = "mygame"
version = "0.2.1"
# Where modules live, relative to the manifest. Defaults to "src".
source = "src"

[dependencies]
core = { path = "../core", version = "^1.2" }
math = { path = "vendor/math" }

[lints]
# Any diagnostic code, set to off, hint, perf, warning or error.
W0101 = "off"
W0102 = "error"

[build]
# "deny" forbids `unsafe` blocks anywhere in this package.
unsafe = "allow"
# What this package may do at all. Omit the key to leave it unrestricted;
# an empty string sandboxes it completely.
capabilities = "io"

Only the name key of [package] is required. Unknown keys and tables are reported rather than ignored, so a typo in a key name is caught instead of silently doing nothing.

The format is a deliberately small subset of TOML: tables, string values and inline tables. A package manifest needs nothing more, and a small parser with precise diagnostics is worth more than a complete one with vague ones.

A dependency may say which versions it accepts (D242): version = "^1.2", in Cargo's grammar. 1.2 means ^1.2; ~, =, >=, >, <=, < and * work as they do there, and a comma is "and" (">=1.2, <2"; the manifest reader respects commas inside quotes). Nothing is resolved: the one copy found must satisfy the requirement, or the build reports E0053 naming the package that asked. A bare string, std = "1.2", is a version in every other manifest, so it is E0053 until a registry exists; it is no longer read as a path.

Dependencies are a path or a remote repository pinned by rev or tag (wolang fetch writes wolang.lock, D141). A registry is a later wave; a build script (build.wo, in the spirit of build.rs) becomes possible once the language is executable in wave 7. The manifest stays declarative data either way, so that any external tool — CI, a registry, a dependency bot — can read a package's name and version without running a Wolang interpreter.

Visibility

no modifiervisible inside the module
offervisible to other modules
privvisible inside the file only

A module's declarations are shared across its files, so two files in one directory see each other's names without needing anything. Declaring the same name twice in one module is an error (E0057), reported on both declarations.

Needing names

wolang
need mygame.combat                  // the whole module
need mygame.combat.{Damage, Weapon} // selected names

A need names a module, not a file. Needing a name the module does not declare is E0056; importing one it declares but does not export is E0058.

Cycles between packages are an error (E0059). Cycles between modules inside one package are fine: a module's names are known from its declarations, which do not depend on the modules it imports.

Capabilities

capabilities is how a package is sandboxed. The value is an effect list, spelled the way a uses clause is, and anything outside it is E0703 — not a mistake in the code, but a permission the package was not given.

Text
[build]
capabilities = "io"

Omitting the key leaves a package unrestricted. capabilities = "" grants nothing. unsafe = "deny" is the same idea narrowed to one effect.

A sandboxed package cannot declare extern at all (E0705): it reaches the outside world through packages that are not sandboxed, and every one of those says which capability each door needs. The standard library's extern declarations carry it — wolang_fd_read is uses io, a socket is uses net, the clock is uses time — so std.fs.Open is io to whoever calls it, however many safe wrappers sit in between.

A mod does not get to write its own grant. A host loads one with wolang_vm_load_mod(vm, path, "io"): the capabilities are the host's, the mod's manifest can narrow them and cannot widen them, unsafe is denied and its [link] table is dropped (D217).

Checking without a package

A single file can be checked on its own:

Shell
wolang check src/combat/damage.wo

Such a file belongs to no module, so its need declarations are not resolved and no import diagnostics are produced — lexical, syntactic and later type errors are still reported in full. This is what makes a scratch file or a bug report reduction usable.

The cache

Text
mygame/.wolang-cache/items.wdb

Checking a package directory writes this file and reads it next time. It holds the item tree of every source file — each declaration's kind, name, nesting and signature hash — together with the hash and size of the text it came from. A file whose text still matches skips lexing and parsing entirely.

The cache is a pure optimization and is never trusted: a changed file, a corrupt file, a truncated file or one written by a different compiler build is discarded. --no-cache skips it in both directions, which is how a suspected cache problem is ruled out.

Commands

Shell
wolang check <paths>      # files or package directories
wolang run <paths>        # run `main` on the JIT (`--interpret` for the interpreter)
wolang test <paths>       # run every `@Test` function
wolang modules <dir>      # print the package and module graph
wolang fmt <files>        # print the formatted form
wolang fmt --check <f>    # fail if a file is not formatted
wolang fmt --write <f>    # rewrite in place
wolang ir <files>         # print the IR
wolang ast <files>        # print the syntax tree
wolang tokens <files>     # print the token stream

examples/package is a working package to try these on, lib/std is the standard library, and wolang run examples/hello.wo prints hello, world.

run uses the JIT where the dev tier can take the program and the interpreter, which is the reference semantics, where it cannot; --interpret forces the interpreter. The differential check lives in test: every @Test runs in both tiers and a disagreement fails it, because a difference there is a miscompile.

Page feedback

Was this page helpful?