# pkg — the @fetch package system

`@fetch` downloads versioned dependencies at **compile time** (it is a
module-level directive, resolved before compilation — never inside function
bodies) and splices their functions into your program.

```rinne
@import = .{ std };
@fetch("https://example.com/math.rg");
@fetch("github.com/user/lib", .{ .version = "v1.2.0" });
```

## Accepted targets

| Form                                  | Behavior                                        |
|---------------------------------------|-------------------------------------------------|
| `https://.../pkg.rg`                  | direct source file                              |
| `http(s)://.../pkg.tar.gz` / `.tgz`   | archive; entry = `main.rg`, or the only `*.rg`  |
| `github.com/u/r` / `gitlab.com/g/sub/r` / `codeberg.org/u/r` | repo shorthand — **requires** `.version`; rewritten to the host's tag archive URL |

Options struct:

- `.version = "v1.2.0"` — required for shorthands, optional (but recommended)
  for direct URLs; it also keys the cache.
- `.sha256 = "<64 hex>"` — pin content; mismatch aborts with both digests
  printed.

## Caching & offline mode

- Cache root: `$RINNE_CACHE_HOME` else `$HOME/.cache/rinne/pkg`.
- Each package lands in a content-keyed directory with a `manifest.json`
  (`url`, `version`, `final_url`, `entry`, `sha256`). Repeat builds are pure
  cache hits.
- `RINNE_OFFLINE=1` refuses uncached packages instead of hitting the network.

## Rules

- Package files may contain **only function declarations** (no global
  statements, no nested `@fetch`).
- Name collisions are reported as `'<name>' ... conflicts` naming both sides.
- The old spelling is retired:

```
@import = .{ std };
compile error: '@fetch_pkg' was renamed to '@fetch'
```

## Runnable example

Serve a file locally to try it without touching the network:

```bash
mkdir -p /tmp/mysrv && printf 'fn add(a: int, b: int) int {\n    return a + b;\n}\n' > /tmp/mysrv/util.rg
(cd /tmp/mysrv && python3 -m http.server 8901 &)
```

```rinne
@import = .{ std };
@fetch("http://127.0.0.1:8901/util.rg", .{ .version = "v1", .sha256 = "..." });

pub fn main() int {
    std.print("{}\n", .{add(2, 3)});
    return 0;
}
```

## More examples

See `examples/pkg_demo.rg` — fetches a package from a local server and calls into it.