bux-lang/docs/Packages.md

Bux Package Manager

Status: Path + git + local/file registry (E.1) + HTTP(S) index URL (cached under ~/.bux/cache/).

See also: SEMVER.md for version policy.

---

Manifest (bux.toml)

Every Bux package has a bux.toml at the project root.

[Package]
Name    = "MyApp"
Version = "0.1.0"
Type    = "bin"          # bin | lib | shared | static
Authors = ["Your Name <you@example.com>"]
License = "MIT"

[Build]
Output = "Bin"

[Dependencies]
greet = { Path = "/abs/path/to/greet" }
Json  = { Version = "2.1", Source = "https://github.com/bux-lang/json" }
Utils = { Path = "../Utils" }
# Registry name-only (resolved by `bux add` / `bux install`):
# greet = "0.1.1"

Dependency Forms

Form	Example	Description
Version string	greet = "0.1.1"	Registry dependency
Wildcard	greet = "*"	Latest registry version
Inline table (git)	{ Version = "1.4", Source = "https://..." }	Git URL + version
Inline table (path)	{ Path = "../Lib" }	Local path dependency

---

Package registry (E.1)

Index file

Default locations (first hit wins):

1. $BUX_REGISTRY — local path or http(s):// URL to a registry.toml
2. ~/.bux/registry.toml
3. config/registry.toml next to the Bux repo / compiler

HTTP(S) indices are fetched with curl (or wget) into ~/.bux/cache/registry_http.toml. Set BUX_REGISTRY_REFRESH=1 to force re-download. Relative file: / path: entries in a remote index resolve against the cache directory — prefer absolute paths or git URLs for HTTP-served registries.

Self-signed HTTPS registries (dev/smoke): BUX_REGISTRY_INSECURE=1 adds curl -k / wget --no-check-certificate. Do not use this in production.

Format:

[[package]]
name = "greet"
version = "0.1.1"
source = "file:../registry/packages/greet"   # relative to the index file
description = "Hello helpers"

[[package]]
name = "net"
version = "1.0.0"
source = "https://github.com/example/bux-net.git"
description = "TCP helpers"

file: / path: sources are resolved relative to the registry file (or the HTTP cache path). Git URLs are cloned into ~/.bux/packages/<name>/ on install.

# Local index (default in this repo)
export BUX_REGISTRY=/path/to/config/registry.toml

# Remote index URL
export BUX_REGISTRY=https://example.com/bux/registry.toml
bux search

CLI

# Search the index
bux search
bux search greet

# Add by registry name (writes Path or git Source into bux.toml)
bux add greet
bux add greet 0.1.1

# Explicit sources still work
bux add utils --path "../utils"
bux add network --git "https://github.com/bux-lang/network"

# Resolve + write bux.lock (includes Checksum of package *.bux sources)
bux install

# CI: verify lock only (no re-resolve; fails if missing or checksum mismatch)
bux install --locked

Lockfile (bux.lock)

Generated by bux install. Each entry:

[[Package]]
Name = "greet"
Version = "0.1.1"
Source = "/abs/path/or/git-url"
Checksum = "sha1-of-sorted-bux-sources"

• Reproducible: running install twice with the same deps yields the same lock.
• --locked: cloud/CI mode — does not rewrite the lock; verifies paths exist and Checksum still matches. Fail-closed if the lock is missing or corrupt.

Demo package in this monorepo: registry/packages/greet (registered in config/registry.toml). Smoke test: tools/smoke_registry.sh (local + lock + --locked + HTTP + HTTPS).

Selfhost (buxc2) package manager parity (sessions 80–81):

buxc2 search [query]
buxc2 add greet              # registry resolve
buxc2 add greet 0.1.1
buxc2 install / install --locked
make test-selfhost-install
make test-selfhost-registry  # search + add + HTTP index + run

$BUX_REGISTRY / HTTP(S) cache / BUX_REGISTRY_INSECURE match bootstrap.

---

CLI Commands

bux add <name> [version]

Add a dependency to bux.toml (registry / --path / --git).

bux search [query]

List packages in the active registry (filter by name/description).

bux install

Resolve dependencies and generate bux.lock.

What it does:

1. Reads [Dependencies] from bux.toml
2. Resolves path-based deps (verifies directory exists)
3. Clones git-based deps to ~/.bux/packages/<name>/
4. Resolves bare version names via the registry index
5. Generates bux.lock with exact versions and sources

bux build / bux run

Automatically reads bux.lock and merges dependency source files into the build.

bux build   # Compile with all dependencies
bux run     # Build and run

---

Lockfile (bux.lock)

Auto-generated. Do not edit manually.

[[Package]]
Name = "greet"
Version = "0.1.1"
Source = "/home/user/z-git/bux/bux/registry/packages/greet"

[[Package]]
Name = "utils"
Version = "0.1.0"
Source = "/home/user/projects/utils"

The lockfile ensures reproducible builds — every developer gets the exact same dependency versions.

---

Dependency Resolution Rules

1. Path-based deps are resolved relative to the manifest directory
2. Git-based deps are cloned to ~/.bux/packages/<name>/
3. Version-based deps look up config/registry.toml (or $BUX_REGISTRY)
4. Dependencies are loaded from <dep>/src/*.bux at build time
5. Later declarations shadow earlier ones (project > deps > stdlib)

---

Example: Creating a Library

bux new mylib
cd mylib
# Edit src/*.bux → module MyLib { func Add(...) }
# Set Type = "lib" in bux.toml
# Register in your registry.toml with source = "file:..."
bux build

Example: Using a Library

bux new myapp
cd myapp
bux add mylib --path "../mylib"
bux install
# Edit src/Main.bux → import MyLib::Add;
bux run