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
@@ -58,6 +58,9 @@ Klein/
|
||||
import engine.engine // the same line works in game/app/main.rex and in any other file
|
||||
```
|
||||
|
||||
`rex init` writes one for you. The same file lists the packages the project uses
|
||||
(see [chapter 14](14-packages.md)).
|
||||
|
||||
Rex finds the nearest `rex.toml` above the file you run (and above each file you open in an
|
||||
editor). Without one, imports are counted from the folder of the file you run, as above. With
|
||||
one, even a file next to your main file is imported with its full path (`import game.app.util`).
|
||||
|
||||
@@ -124,6 +124,7 @@ import tools.fs // tools/fs.rex, used as fs.name
|
||||
import ..shared // ../shared.rex (...x = two folders up)
|
||||
// rex.toml in the top folder: imports count from there, in every file
|
||||
import os // built-in: os math time rand
|
||||
import json // a package: `rex add git.joji.li/joji/json` (see chapter 14)
|
||||
pub func f() {} // visible to other files
|
||||
```
|
||||
|
||||
@@ -147,6 +148,8 @@ lib.fill(buf, n) // T* parameters take a variable or a list
|
||||
## Commands
|
||||
`rex run f.rex args…` · `rex build f.rex -o out` · `rex check f.rex` · `rex test [path]` · `rex emit-c f.rex` · `rex fmt path` (`--check` to only report) · `rex lsp` (editor server) · `rex header x.h [word]` (what a C header offers)
|
||||
|
||||
Packages: `rex init` · `rex add git.host/owner/name[@v1.2.0]` (or `../folder`) · `rex remove name` · `rex update [name]` · `rex get` · `rex deps`
|
||||
|
||||
## Things that stop the program (exit code 2)
|
||||
Divide by zero · list index/slice out of range · `pop` on an empty list · reading a missing
|
||||
map key with `m[k]` · using a `nil` or gone `weak` value · calling a `nil` function or interface ·
|
||||
|
||||
@@ -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.
|
||||
@@ -22,6 +22,7 @@ These notes teach it from zero. Read them in order, or jump to the
|
||||
| 11 | [Cheatsheet](11-cheatsheet.md) | Everything on one page |
|
||||
| 12 | [A real program](12-calculator-walkthrough.md) | A calculator, split over five files |
|
||||
| 13 | [C and C++ libraries](13-c-libraries.md) | `import "raylib.h"`, your own C code |
|
||||
| 14 | [Packages](14-packages.md) | `rex add`, using code from other projects |
|
||||
|
||||
## How to read the examples
|
||||
|
||||
|
||||
Reference in new issue
Block a user