trident

The `trident` commands

Every trident subcommand with its arguments, grouped into building, managing dependencies, and publishing and auditing.

since 0.1.0-alpha.1linux

Description

trident takes a subcommand first. Most subcommands end with an optional [manifest-or-dir]: the path of a trident.toml, or of a directory that contains one. It defaults to the current directory. Running trident with no arguments, or with an unknown subcommand, prints this usage text and exits with status 2:

usage: trident <build|run|check|emit-llvm|plan> [manifest-or-dir] [--out <path>] [--target <triple>] [--opt-level <0|2>] [--plan <path>] [--leviathan <path>] [--vendor]
       trident add <path>[@version] [--as <name>] [--dev] [manifest-or-dir]
       trident remove <path> [manifest-or-dir]
       trident update [<path>] [manifest-or-dir]
       trident lock [manifest-or-dir]
       trident fetch [manifest-or-dir]
       trident why <path> [manifest-or-dir]
       trident audit [manifest-or-dir] [--policy <file>]
       trident vendor [manifest-or-dir]
       trident publish [manifest-or-dir] [--tag vX.Y.Z] [--path <vcs-path>]
          [--sign-key <private.pem> --identity <name> [--artifact <file>]
           [--attestation-out <file>]]
       trident yank <path>@<version>
       trident attest [manifest-or-dir] --key <private.pem> --identity <name>
          [--path <vcs-path>] [--artifact <file>] [--out <file>]
       trident audit-record <path>@<version> --auditor <name> [--file <path>]
          [manifest-or-dir]
       trident --version

Building

These commands read trident.toml, resolve dependencies and write the build plan, and all but plan then start the compiler. trident.overview explains how.

Command	What it does
`build`	Compiles the project to a native executable with `leviathan --build-native`.
`run`	Runs the project with `leviathan --run`. It does not pass arguments to the program.
`check`	Checks the project without running it, including development-only dependencies.
`emit-llvm`	Prints the project as LLVM IR.
`plan`	Writes the plan, prints its path, and starts no compiler.

Flag	Meaning
`--out <path>`	The executable's name; the default is the manifest's `out`, then `name`.
`--target <triple>`	The machine to build for (see `lang.cross-compilation`).
`--opt-level <0\|2>`	`0` for a quick debug build, `2` (the default) to optimise. `--release` means `2`.
`--plan <path>`	Where to write the plan; the default is `build/plan.lvplan`.
`--leviathan <path>`	The compiler to use instead of the one `trident` would find.
`--vendor`	Read dependencies only from `./vendor` and the lock.

Managing dependencies

None of these starts the compiler.

Command	What it does
`add <path>[@version] [--as <name>] [--dev]`	Adds a `[[dep]]` table to the manifest and locks. Without `@version` it asks the repository for its newest tag. `--as` sets the `as` key and `--dev` sets `dev = true`.
`remove <path>`	Removes the dependency from the manifest and locks again.
`update [<path>]`	Moves one repository dependency, or all of them, to the newest version of the same major version, then locks.
`lock`	Recomputes `trident.lock` from the manifest and fetches what is missing.
`fetch`	Like `lock`, and reports how many modules were fetched.
`why <path>`	Shows the version chosen for a module and which projects require it.
`vendor`	Copies every locked module into `./vendor`.

add, remove and update rewrite the whole manifest; comments in it are not kept.

Publishing and auditing

Command	What it does
`audit [--policy <file>]`	Verifies every locked module against the checksum record and the lock, and enforces a trust policy when there is one.
`publish [--tag vX.Y.Z] [--path <vcs-path>]`	Creates the immutable tag for the package's version. With `--sign-key <private.pem> --identity <name>` it also writes a signed attestation, to `--attestation-out <file>` if given. `--artifact <file>` adds a built file's hash.
`yank <path>@<version>`	Stops new resolutions from choosing a version; existing locks keep working.
`attest --key <private.pem> --identity <name>`	Writes a signed attestation for the package, to `--out <file>` or a default place. `--path` and `--artifact` as for `publish`.
`audit-record <path>@<version> --auditor <name>`	Appends a review record to `trident.audits.toml`, or to the file named by `--file`.

Exit status

build, run, check and emit-llvm exit with the compiler's status. Every other failure exits with 1, and a malformed command line, such as a missing argument or an unknown option, exits with 2.

A project to run the commands on

string name = "Leviathan";
console.writeln("hello from ${name}");

Run it ▶

hello from Leviathan

Rules

The first argument is the subcommand. Options and the optional [manifest-or-dir] follow it.
An option that is not in the usage text is an error.
build, run, check, emit-llvm and plan find the compiler with --leviathan, then LEVIATHAN, then the directory of the trident program, then the PATH.
add, remove, update, lock, fetch, why, audit, vendor, publish, yank, attest and audit-record never start the compiler.
<path>@<version> takes a repository path and a MAJOR.MINOR.PATCH version.

Examples

A project of one file, built for debugging and then for release:

name    = "hello"
entry   = "main.lev"
sources = ["main.lev"]

trident run .
trident build . --out hello-debug --opt-level 0
trident build . --release

The minimal source that manifest builds:

main.lev

console.writeln("hello");

Run it ▶

Adding a repository dependency, checking it and removing it again:

trident add github.com/acme/json@1.2.0 --as Json
trident why github.com/acme/json
trident audit
trident remove github.com/acme/json

Releasing a package:

trident publish . --path github.com/acme/json
git push origin v1.2.0

Notes

trident --version prints the version of trident and then of the compiler it finds. If it does not find a compiler it says so.
Where the build plan, the lock file and the vendor directory go is described on trident.overview and trident.versions-and-integrity.

The trident commands