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