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>
133 lines
4.4 KiB
Markdown
133 lines
4.4 KiB
Markdown
# 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.
|