Add a package manager: rex init/add/remove/get/update/deps

Packages come from git (a registry can be added later; a bare version in
rex.toml is reserved for it). rex.toml [deps] names them, rex.lock pins exact
commits, and run/build/check/test download what is missing. `import json`
reads the package's json.rex; package files get `@json...` module keys so they
never mix with the project's own files. Newest tag of the same major version
wins when packages disagree. The language server reads downloaded packages.
Docs: docs/14-packages.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Your NameandClaude Opus 5.5 committed 2026-11-16 10:30:11 +01:00
1 parent 300d767124
commit 15da1e2379
16 files changed
+1588 -61

No files matched your search

+132
View File
@@ -0,0 +1,132 @@
# 14. Packages
A **package** is Rex code from another project that you use in yours: a JSON reader,
a game library, helpers a friend wrote. Rex gets packages straight from **git**: any git
repository with Rex files in it is a package. There is no website you have to upload to.
## Using a package
Start a project (once), then add the package with its git address:
```text
$ rex init
wrote rex.toml (the project `game`)
$ rex add git.joji.li/joji/json
fetching git.joji.li/joji/json
downloading json v1.2.0
added json v1.2.0 (use it with `import json`)
```
Now import it like one of your own files:
```rex
import json
func main() {
var v = json.parse("[1, 2]")?
print(v)
}
```
`rex run`, `rex build`, `rex check` and `rex test` download whatever is missing by themselves.
- The address is written without `https://` (it is added for you). `https://...`,
`ssh://...` and `git@host:owner/repo` work too, for private repositories.
- Without a version, `rex add` takes the newest one. Pick one with `@`:
`rex add git.joji.li/joji/json@v1.1.0`. After the `@` can also come a branch
(`@main`) or a commit.
- A repository without any versions is followed on its main branch.
- `rex remove json` stops using it.
## rex.toml and rex.lock
`rex add` writes the package into `rex.toml`, in the top folder of your project:
```toml
[package]
name = "game"
[deps]
json = "git.joji.li/joji/json@v1.2.0"
mylib = "../mylib"
```
You can edit this file yourself too; the next `rex run` picks it up.
Next to it, rex writes **`rex.lock`**. It remembers the exact commit of every package,
so your program builds the same tomorrow, on another computer, even if a package's author
changes something. Keep both files with your code (commit them). Don't edit `rex.lock`.
## Newer versions
Versions are git tags like `v1.2.0`: **major.minor.patch**. A change in the first number
(`v2.0.0`) means the package changed in ways that may break your code.
```text
$ rex update
json v1.2.0 -> v1.4.1
json: v2.0.0 is out too (a new major version may need changes in your code: `rex add git.joji.li/joji/json@v2.0.0`)
```
`rex update` moves every package to its newest version **with the same first number**, and
packages that follow a branch to its newest commit. `rex update json` does only that one.
Jumping to a new major version is up to you, with `rex add ...@v2.0.0`.
`rex deps` shows what your project uses, and what those packages use in turn:
```text
$ rex deps
json v1.4.1
strs v1.0.3
mylib (folder ../mylib)
```
## A package in a folder
A folder on your computer works as a package too: `rex add ../mylib`. Changes in that
folder show up at the next run, with nothing to update. It is the easy way to share code
between your own projects, or to try changes to a package before you publish them.
## Making a package
A package is a folder (a git repository, to share it) with a `rex.toml` and a file with the
package's name:
```text
json/
rex.toml [package] name = "json"
json.rex what `import json` gives
parser.rex what `import json.parser` gives
```
```rex
// json.rex
import parser // the package's own parser.rex
pub func parse(text: string): (parser.Value, error) {
return parser.read(text)
}
```
- Imports inside a package count from the package's top folder, as in any project. A
package's `parser.rex` and your own `parser.rex` are different files, so names never clash.
- A package can use other packages: list them in its own `rex.toml` under `[deps]`.
Rex downloads those too. If two packages want different versions of the same package, the
newer one is used (as long as the first number is the same; otherwise it's an error that
names who wants what).
- Only `pub` things can be used from outside, as with your own files.
- To publish a version: `git tag v1.0.0` and `git push --tags`.
## Good to know
- Packages are kept in `~/.cache/rex` (or the folder in `$REX_HOME`). Deleting it is safe:
they come back at the next run.
- Once everything is downloaded, building needs no internet.
- Your editor sees packages that are downloaded. After adding one by hand to `rex.toml`, run
`rex get` (or any `rex run`) so the editor can find it.
- A package's name is the same as its `[package] name`, written in lowercase letters,
digits and `_`. If yours has a file `json.rex` and you add a package called `json`, Rex
says so: rename one of them.
- There is no package website yet. `json = "1.2.0"` (a version without an address) is kept
for that and is an error for now.