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:
1 parent
300d767124
commit
15da1e2379
16 files changed
+1588
-61
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user