Reference

std/project/lib

std/project/src/lib.trb

The vocabulary of project.trb: Project, Dependencies, Program, Profile, Test, Tasks, Workspace, Registry and Source. A project file is a receiver script against Project, so everything a project can say about itself is a var field or a method of the types here - and nothing else is needed to write one, because a setting is written name = "acme/shop" and a section tasks { ... }.

The types are ordinary data, not native: a project file is deterministic and has no IO, so evaluating it is nothing but running these members. This is what makes a project.trb type check against a real sandbox, with the same vocabulary the toolchain's own static reading of the file understands.

type Registry

type Registry

An owner bound to a registry, so a public package can never take the place of a private one.

field owner

owner: String

The owner part of every owner/name this registry answers for.

field url

url: String

Where the registry is reached.

type Source

type Source

Where one package comes from instead of the registry its owner is bound to (docs/design/PROJECT.md section 7): a directory (path), a git repository at a revision (git, revision), or an archive with its hash (archive, hash). Exactly one of path, git and archive is set.

field package

package: String

The owner/name whose location this is.

field path

path: String = ""

Not documented.

field git

git: String = ""

Not documented.

field revision

revision: String = ""

Not documented.

field archive

archive: String = ""

Not documented.

field hash

hash: String = ""

Not documented.

type Dependencies

type Dependencies

What a project depends on. A requirement is written as it is published - "acme/http:^1.2.3" - because the version is the business of the package manager and the project file only names what it wants.

field runtimeRequirements

protected var runtimeRequirements: List<String> = []

What dependents get too.

field developmentRequirements

protected var developmentRequirements: List<String> = []

Tests and tools. Never part of what dependents get.

fn runtime

var fn runtime(...requirements: String)

Adds requirements that dependents get as well: dependencies { runtime "acme/http:^1.2.3" }.

fn development

var fn development(...requirements: String)

Adds requirements for tests and tools only, never part of what a dependent gets.

type Program

type Program

A program of the package beyond the src/main.trb that needs no line (docs/design/PROJECT.md section 4): program "migrate", entry: "tools/migrate.trb". A line without an entry renames that default program: program "torb".

field name

name: String

The name of the program, of its binary, and of the argument to torb run and torb build.

field entry

entry: String = ""

The file whose top-level code the program is, relative to the project. Empty renames src/main.trb.

field output

output: String = ""

Where the binary goes, relative to the project and taken literally. Empty is build/<profile>/<name>.

type Profile

type Profile

How one of the two profiles builds (docs/design/PROJECT.md section 5): profile "release" { optimize = 3 }. The profiles are dev and release and there is no third; a setting the back end does not have yet is read and ignored.

field name

name: String

dev or release.

field optimize

var optimize: Int = 1

How hard the C compiler optimizes, 0 to 3: 1 in dev, 2 in release.

field debugInformation

var debugInformation: Bool = false

Whether the binary carries debug information for a debugger: in neither profile unless a block says so.

field panicFrames

var panicFrames: Bool = true

Whether a panic prints the frames that led to it: in dev, not in release. Read, and ignored for now.

fn named

static fn named(name: String): Self

The profile where no block says otherwise.

type Test

type Test

What torb test runs: every file called *.test.trb in the package.

field coverageThreshold

var coverageThreshold: Int = 0

The share of lines a test run has to cover, in percent. 0 asks for nothing.

type Tasks

type Tasks

How the program's tasks run (docs/design/CONCURRENCY.md section 3): workers threads run tasks, the core count where the line is left out, and blocking threads run what blocks (offload), 4 where it is left out. TORB_WORKERS and TORB_BLOCKING override both where the program runs. 0 is "not said"; a number the toolchain reads has to be 1 to 1024.

field workers

var workers: Int = 0

Not documented.

field blocking

var blocking: Int = 0

Not documented.

type Workspace

type Workspace

A project that consists of several projects. Every member is an ordinary project with a project.trb of its own; a pattern is a directory or directory/* for every project directly below it.

field memberPatterns

protected var memberPatterns: List<String> = []

The patterns Workspace.members added.

fn members

var fn members(...patterns: String)

Adds member patterns: workspace { members "packages/*" }.

type Project

type Project

The receiver of project.trb. A setting is a var field (name = "acme/shop" writes it), a section is a field that is configured in place (tasks { ... }), and only what is more than that is a method (authors, registry, program, profile).

The fields are readable, which is what lets a project file compute from what it has already said: description = "The {name} package".

field name

var name: String = ""

owner/name. Owners are verified namespaces of a registry, so a bare name is not publishable.

field version

var version: String = ""

The published version, in the package manager's format.

field language

var language: String = ""

The oldest version of the language the project needs: language = "0.3.0".

field description

var description: String = ""

One sentence about the package: required to publish it.

field license

var license: String = ""

The license, as an SPDX expression ("MIT", "MIT OR Apache-2.0"): required to publish it.

field repository

var repository: String = ""

Where its source is read: "https://github.com/acme/shop".

field prelude

var prelude: String = "std/prelude"

The package whose public names are in scope in every file of the project.

field dependencies

var dependencies: Dependencies = Dependencies()

What the project needs, split into what dependents get and what stays inside the project.

field test

var test: Test = Test()

What torb test runs.

field tasks

var tasks: Tasks = Tasks()

How the program's tasks run: the workers of its pool and the threads of its blocking pool.

field workspace

var workspace: Workspace = Workspace()

The other projects this one is a workspace of, if any.

field authorNames

protected var authorNames: List<String> = []

The names Project.authors added.

field registries

protected var registries: List<Registry> = []

The bindings Project.registry added.

field sources

protected var sources: List<Source> = []

The locations Project.source added.

field programs

protected var programs: List<Program> = []

The programs Project.program declared, in order.

field profiles

protected var profiles: List<Profile> = []

The profiles Project.profile configured, in order.

fn authors

var fn authors(...names: String)

Names the people or organizations behind the project: authors "Ada Lovelace".

fn registry

var fn registry(owner: String, url: String)

Binds an owner to the registry its packages come from: registry "acme", url: "https://packages.acme.test".

fn source

var fn source(package: String, path: String = "", git: String = "", revision: String = "", archive: String = "", hash: String = "")

Says where a package comes from instead of its owner's registry: source "acme/y", path: "../y", source "acme/x", git: "https://git.acme.test/x", revision: "v1.2.3", or source "acme/z", archive: "https://files.acme.test/z-1.0.tar.gz", hash: "sha256:...".

fn program

var fn program(name: String, entry: String = "", output: String = "")

Declares a program beyond src/main.trb: program "migrate", entry: "tools/migrate.trb", or renames that one: program "torb". The three are read before anything runs, so they are plain strings.

fn profile

var fn profile(name: String, configure: (var self: Profile) => Void)

Configures one of the two profiles: profile "release" { optimize = 3 }.

fn settings

fn settings(): String

The settings as the literal statements that would produce them, one per line, in the order of this type: the settings block of the locked manifest (docs/design/PROJECT.md section 8), and the text the toolchain reads back from an evaluated project.trb (docs/design/SCRIPTS.md section 7). A setting at its default is left out, because the reader has defaults of its own: a workspace without a test section has no test directory.

A field is printed back with = (name = "acme/shop"); a method - runtime, development, members, authors, registry - is printed back as the command call that reaches it.

fn evaluated

fn evaluated(script: (var self: Project) => Void): String

What the toolchain runs to evaluate a project.trb (docs/design/SCRIPTS.md section 7): a fresh Project, configured by the script, printed back as its settings. It is the host of the script inside the VM's sandbox, and nothing a program needs.