Packages and modules
A package is a directory with a wolang.toml manifest. A module is a directory of .wo files inside it:
Layout
A package is a directory with a wolang.toml manifest. A module is a
directory of .wo files inside it:
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.physicsA 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
[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 modifier | visible inside the module |
offer | visible to other modules |
priv | visible 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
need mygame.combat // the whole module
need mygame.combat.{Damage, Weapon} // selected namesA 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.
[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:
wolang check src/combat/damage.woSuch 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
mygame/.wolang-cache/items.wdbChecking 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
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 streamexamples/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.