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>
4.4 KiB
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:
$ 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:
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://...andgit@host:owner/repowork too, for private repositories. - Without a version,
rex addtakes 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 jsonstops using it.
rex.toml and rex.lock
rex add writes the package into rex.toml, in the top folder of your project:
[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.
$ 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:
$ 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:
json/
rex.toml [package] name = "json"
json.rex what `import json` gives
parser.rex what `import json.parser` gives
// 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.rexand your ownparser.rexare different files, so names never clash. - A package can use other packages: list them in its own
rex.tomlunder[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
pubthings can be used from outside, as with your own files. - To publish a version:
git tag v1.0.0andgit 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, runrex get(or anyrex 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 filejson.rexand you add a package calledjson, 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.