bux-lang/docs/Packages.md

# Bux Package Manager

> **Status (v1.0):** Path + git + **local/file registry** + **HTTP(S) index URL**  
> (cached under `~/.bux/cache/`). Lockfile + `bux install --locked` for CI.

See also: [SEMVER.md](SEMVER.md) for version policy (active as of language **v1.0.0**).

---

## Manifest (`bux.toml`)

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

```toml
[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:

```toml
[[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.

```bash
# 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

```bash
# 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:

```toml
[[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):

```bash
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.

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

---

## Lockfile (`bux.lock`)

Auto-generated. **Do not edit manually.**

```toml
[[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

```bash
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

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