raft creates projects and fetches, pins and audits their dependencies. Its unusual feature
is that packages declare their effects, and raft refuses to install one that needs an
effect your project hasn't allowed.
Commands#
| command | does |
|---|---|
raft new <name> [--lib] |
create <name>/ with raft.toml, .gitignore and src/main.auk (or src/lib.auk) |
raft add <pkg> |
add the latest version of a package, then install |
raft add <pkg> --path <dir> |
add a local package by path |
raft add <pkg> --url <url> |
add a package bundle served at an http:// or https:// URL |
raft remove <pkg> |
drop a dependency, then install |
raft install |
resolve, check effects, copy packages into .raft/, write raft.lock |
raft list |
show the dependency tree with versions and effects |
raft pack [<dir>] |
write the package as one file, <dir>/<name>.raft (default: the project), for serving from a URL |
Every command finds the project by searching upward from the current directory.
Installing is all-or-nothing. Versions, effects and checksums are all checked before anything
is written; on any error nothing changes, and add and remove put raft.toml back as it
was.
raft.toml#
[package]
name = "weather"
version = "0.1.0"
effects = ["net", "fs"] # the most this package and its dependencies may do
[deps]
http = "^0.1" # from the registry
json = "^0.1"
geo = { path = "../geo" } # a local package
maps = { url = "https://example.com/pkgs/maps.raft" } # a bundle at a URL
[link]
libs = ["sqlite3"] # C libraries, for packages that use ffiname: lowercase letters, digits and_. It cannot be the name of a core module (fs net time rand env proc ffi str int float bool math core).version:MAJOR.MINOR.PATCH.effects: any offs net time rand env proc gui audio_out ffi. The default is none.[link]: see Calling C.
Version requirements#
| written | accepts |
|---|---|
"^1.2" or "1.2" |
1.2.0 up to, not including, 2.0.0 |
"^0.3" |
0.3.0 up to, not including, 0.4.0 |
"^0.0.3" |
exactly 0.0.3 |
"~1.2.3" |
1.2.3 up to, not including, 1.3.0 |
"=1.2.3" |
exactly that |
"*" |
anything |
A build contains one version of each package.
Effects are checked on every edge#
Each package's effects must be a subset of the effects of the package that depends on it.
A dependency can therefore never do more than its parent allows, and your project's own list
bounds the whole tree.
$ raft add http
error: http 0.1.1 needs effect `net`, but weather's raft.toml only allows []
help: add "net" to [package] effects in raft.tomlAllowing an effect is a decision you make once, in one visible place, and it shows up in code
review as a one-line diff. raft list then answers "what can my dependencies do?" at a
glance:
$ raft list
weather 0.1.0 uses net
├── http 0.1.1 uses net
│ ├── json 0.1.0
│ └── url 0.1.0
│ └── encoding 0.1.0
└── csv 0.1.0The compiler enforces the same list inside each package, so a package cannot use an effect it didn't declare. See Effects.
raft.lock#
raft install writes the exact version, source, effects and checksum of every resolved
package:
[[package]]
name = "http"
version = "0.1.1"
source = "registry"
effects = ["net"]
checksum = "sha256:9f2c…"Commit it. The checksum is a SHA-256 over the package's files, and raft install verifies
both the registry's (or URL's) copy and the installed copy in .raft/ against it, failing
loudly on a mismatch, so a URL that starts serving different files is caught. A URL
dependency is recorded as source = "url:<url>". Path dependencies are recorded but not
verified, since you edit them freely.
A package that would be downloaded is taken from .raft/ instead when the lock pins it and
the installed copy still has the locked checksum, so a locked, installed project installs
offline.
Don't commit .raft/; raft new writes a .gitignore for it. After a fresh clone, run
raft install.
The registry#
The registry is a directory of packages (<registry>/<name>/raft.toml) or a URL. By default
it is the packages/ folder of your Auk installation; RAFT_REGISTRY names another:
RAFT_REGISTRY=/path/to/pkgs: a directory, one folder per package.RAFT_REGISTRY=https://example.com/pkgs: any static web server holding one<name>.raftbundle per package (https://example.com/pkgs/json.raft).
Each package has one published version. A hosted registry with many versions per package is planned, and the manifest and lock formats will not change for it.
To use a package of your own, depend on it by path (raft add geo --path ../geo) or by URL
(raft add geo --url https://example.com/geo.raft).
Serving packages from a URL#
raft pack writes a package as one file, <name>.raft, holding raft.toml, README.md and
src/. Put it on any web server (a static host, a release page, an object store):
$ cd geo && raft pack ../site/pkgs
packed geo 0.2.0 -> ../site/pkgs/geo.raft
sha256:4be1…The printed hash is the SHA-256 of the file, and it is exactly the checksum raft.lock will
record for the package. raft follows redirects, verifies TLS certificates (there is no way to
turn that off), and only unpacks the files a bundle may hold, so a bundle cannot write outside
.raft/<name>/.
Writing a package#
$ raft new geo --lib
created geo/ (library)src/lib.aukis the root module. Itspubitems are the package's API, reached asgeo.<item>; other files are submodules (src/shapes.aukisgeo.shapes).- Declare the smallest
effectslist you can. A package with none can be added to any project. If only one function needs the clock, consider taking the time as an argument instead, asdatetimeanduuid.v7do. - Return typed errors (
T!YourErr) so callers can react to them. - Put
testblocks next to the code and aREADME.mdat the top with a short example.
The package catalog lists the official packages.