Modules and dependencies

A directory project uses xu.xun. module: is the module identity, version: its own version, and xu: the Xu version it targets. External imports require an explicit alias and a matching root module in require:.

Local development

With packages beside your app, write app/xu.xun:

module: app
version: !ver 0.1.0
xu: !ver 0.8.8
require:
  "github.com/xulang-org/packages": file:../packages

@main
mysql #github.com/xulang-org/packages/mysql

fn main() {
    _ := mysql.driver()
}

file: is relative to the declaring manifest. Use the root module in require; select mysql, postgres, or other subpackages in the import. Neither XUPATH nor a short import such as #mysql substitutes for this declaration.

Remote modules and version selection

Use a reviewed immutable Git commit, or an exact SemVer minimum requirement when the matching version tag is available:

require:
  "github.com/xulang-org/packages": git:https://github.com/xulang-org/packages.git@<commit>

# Alternative, when this version is available:
require:
  "github.com/xulang-org/packages": v0.1.1

Choose one require block and replace <commit> with an actual commit. MVS reads all reachable version manifests and selects the highest minimum requirement for each module. It does not query latest or interpret version ranges. v2+ modules use a matching /vN path suffix. Explicit file/Git/tar sources remain supported; conflicting sources fail.

Install, lock, and build offline

xu install app
xu check app/main.xu --offline
xu build app/main.xu --frozen --output app/program

Mode	Behavior
Default	May download and establish lock entries; existing content mismatches fail.
`--offline`	No downloads. Uses local sources, verified cache, or vendor; may create lock entries.
`--frozen`	Offline, existing matching lock entries required; no dependency cache or lock writes. Local file dependencies require an installed vendor snapshot.

Commit the reviewed xu.lock. Explicit sources use v2 locks; version graphs use v3. xu install retains all reachable version snapshots in vendor for offline MVS replay. Frozen dependency policy does not freeze your app sources or build output. install --frozen and build --desktop with these modes are rejected.

Proxy and private modules

XUPROXY='https://proxy.example.com,direct' xu install app
XUPRIVATE='example.com/private/*' xu install app

XUPROXY accepts HTTP(S), absolute file:// URLs, direct, and off; the default is direct. A comma falls back only on 404/410; a vertical bar allows fallback on request errors. Identity or integrity mismatches always fail. Direct version discovery supports GitHub repositories; other hosts need an explicit source or a configured Xu proxy.

XUPRIVATE is a comma-separated module-prefix glob list. XUNOPROXY defaults to it and controls proxy bypass. No public Xu proxy is assumed; Go module proxy manifests are not Xu manifests.

Checksum verification in 0.8.4

XUSUMDB accepts a trusted Ed25519 verifier key and optional service URL. For SemVer modules, the client verifies the signed tree head, module digest, inclusion proof, and append consistency before accepting dependencies. With it unset or off, first-use trust remains in effect. XUNOSUMDB controls checksum bypass independently and defaults to XUPRIVATE.

Configured verification failures do not fall back to first-use trust. Offline/frozen builds require previously verified proofs. A public Xu checksum service and independent cross-client witnesses are still pending; configure a service and public key that you trust.

Migrate from older versions

Change old dotted package paths to slash paths; preserve dots in domain names, version numbers, and field/method access. Review changed module identities and legacy lock files before reinstalling. Do not delete a current lock merely to suppress a mismatch.

Use external packages