Packages

You’ll meet: rex add, using code from other projects

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://... 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:

[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.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.

Spotted a mistake? This page comes fromdocs/14-packages.md in the Rex repo.