build.ums manifest reference

A build.ums file, read by the Unified Manifest System (UMS), says what a project is, what it builds, and which commands belong to it. Everything Prismio needs to build a project comes from this one file, and a manifest that is wrong is refused with a code and a line before any compiler work starts. This page is the lookup: the syntax, each block and what it accepts, and a table of every diagnostic the manifest can produce with the change that fixes it. For the same material written as a guide to using the package manager, see the package manager page.

A manifest that uses everything

This manifest declares one of everything the language has. It loads, builds, runs its test, and runs its command with the compiler in this repository.

// Every block, key and call build.ums accepts.
toolchain {
    host = ".prismio/build/debug/prismio"
}

project {
    name = "full-example"
    version = "1.4.0-rc.1+build.7"
    prismio = "0.1"
    description = "Uses every declaration"
    licenseFile = "LICENSE"
    authors = ["Ada Lovelace", "Grace Hopper",]
}

profiles {
    debug {
        overflowChecks = false
    }
    release {
        debugInfo = true
    }
}

targets {
    executable("app") {
        entry = "src/main.psm"
        runtime = "installed"
        exportDynamic = false
        native {
            source("c/util.c")
            include("c/include")
            define("MODE=fast")
            flag("-Wextra")
            responseFile("flags.rsp")
        }
        link {
            library("m")
            search("vendor/lib")
            responseFile("link.rsp")
        }
    }
    test("parser") {
        entry = "tests/parser.psm"
    }
}

dependencies {
    implementation("json", "1.2.0", "../json")
    testImplementation("mock", "0.3.0", "../mock")
}

commands {
    command("notes") {
        description = "Print the notes"
        build("app")
        run("tools/notes.psm")
        run("app", "--verbose", args)
        shell("echo", "done")
    }
}

Only project and at least one target are required. The smallest useful manifest is what prismio init writes:

project {
    name = "hello"
    version = "0.1.0"
    prismio = "0.1"
}

targets {
    executable("hello") {
        entry = "src/main.psm"
    }
}

Syntax

The syntax is small and has no keywords. Every name in a manifest is an identifier, and the meaning of project, targets or executable is decided afterwards, by lowering, from where the name sits. That is why a newer manifest can still be parsed by an older compiler, which then reports the block it does not know instead of failing to read the file.

Semicolons are accepted after a statement and are never needed. Whitespace, including newlines, is insignificant, so a block may be written on one line.

An element with neither arguments nor a block is an error (UMS1102). Statements are read generically first, so a block the loader does not understand is diagnosed by name at the top level (UMS2006) and does not stop the rest of the file from being checked.

Blocks at the top level

A second copy of a block is UMS2007–UMS2014, and any other name at the top level is UMS2006. Anything at the top level that is not a named block, such as a bare assignment, is UMS2005.

toolchain

Names a compiler the project builds for itself, which the installed prismio then uses for every command in the project.

The block must be the first in the file (UMS2403) because an installed compiler reads only this stable prefix before deciding where to forward a command, and it starts the host only if this machine built it. Building it records the file's identity in <host>.trusted beside it. A host that does not match, such as one a cloned repository brought with it, is never started, and the global compiler serves the project with warning P1077. Nothing else may be in this block (UMS2401). See compiler host and promotion.

project

Each key may appear once (UMS2002), values must be string literals (UMS2001), and the block holds properties only (UMS2003) and no other names (UMS2004).

profiles

A profile is the set of build choices behind --release. debug is the default and release is selected by --release.

profiles {
    debug {
        overflowChecks = false
    }
    release {
        debugInfo = true
    }
}

Each profile is written at most once (UMS2702), and the block holds only debug { } and release { } (UMS2701). Every block is checked whether or not it is the selected profile, so a mistake in release is found while building debug. Only the selected profile's block changes the build. A value that is not true or false is UMS2704, and a key other than those two is UMS2703.

targets

Each declaration is kind("name") { ... }.

The name is a string, unique among targets (UMS2105), and follows the name rule above (UMS2308, UMS2104). Its output is .prismio/build/<profile>/<name>, with .exe on Windows.

Any other key is UMS2101, and each key or block may appear once (UMS2102).

native { } takes no arguments (UMS2111) and holds calls that each take one or more strings (UMS2113). Order is kept, because the order of flags and of objects on a link line is meaningful. A name other than these five is UMS2112.

Objects are cached by content, along with every header clang reports reading. See Calling C from Prismio for what invalidates an entry, and runtime platforms and packaging for the driver side.

link { } takes no arguments (UMS2107) and holds calls that each take exactly one string (UMS2109). A name other than these seven is UMS2108.

search and file are not checked for existence when the manifest loads, so a missing one is reported by the linker.

dependencies

Each declaration is scope("name", "constraint") or scope("name", "constraint", "local/path").

A name follows the name rule (UMS2311), a constraint is not empty (UMS2312), and the same name may appear once per scope (UMS2203). A call with the wrong arguments is UMS2202 and any other name is UMS2201. A path is resolved against the directory holding build.ums and must be an existing directory (UMS2210). A dependency with no path is a registry dependency and fails with UMS2211, because there is no registry.

Resolution writes prismio.lock beside build.ums, with root-relative paths, and only when the project declares a dependency. A resolved dependency is not yet on the import search path, and a build that declares one says so with warning P1081.

commands

Each declaration is command("name") { ... }. The name is a string that follows the name rule (UMS2601), is unique (UMS2503), and is not a built-in verb or a name ending .psm (P1062). The body holds an optional description and one or more steps, run in order:

A step needs a string first (UMS2505), an unknown step is UMS2504, and a command with no steps is UMS2602. After the subject, a step argument is a string literal or the bare word args, which splices in whatever the user typed after the command name at that position (UMS2508).

Every step starts in the project root, whatever directory the command was run from. A step that fails ends the command with that step's exit status and P1059.

Diagnostic codes

A manifest diagnostic is printed with the file, line and column of the declaration, and a stable code:

build.ums:11:20: error[UMS2324]: native source 'c/checksum.cpp' is not a C file (.c)

Loading collects every diagnostic it can before printing any, so one run reports several independent mistakes. A diagnostic that reports something missing altogether, such as a required property, points at the block that should have held it.

Reading the table. x stands for the name or value the message fills in. The ranges follow the stage that reports them: UMS0xxx finding the file, UMS1xxx reading it, UMS20xx–UMS23xx lowering and validation of the model, UMS24xx the toolchain block, UMS25xx–UMS26xx commands, UMS27xx profiles and UMS3xxx planning.

Finding and reading the file

Blocks and the project

Targets

Dependencies

The toolchain block

UMS2401–UMS2404 are also used by the dependency writer. umsManifestAddDependency in ums/model/manifest_writer.psm reports UMS2401 (cannot write a dependency with an unknown scope), UMS2402 (invalid dependency name 'x'), UMS2403 (dependency 'x' has an empty version constraint) and UMS2404 (dependency 'x' is already declared in this scope) under the same four numbers. They arise in different places, from the loader and from the writer, so a tool can tell them apart, but a code names two problems for now. Do not match on the number alone if you use the writer.

Commands

Profiles and planning

The codes not listed are not issued. UMS2315 is unassigned, and a number is not reused.

If you are changing the manifest

The pipeline is umsLex, then umsParse, then umsLowerDocument, then validate, then the build plan. Lowering in ums/model/lowering.psm checks shape: which names and arguments are allowed, and what kind of value each key takes. Validation in ums/model/validation.psm checks meaning: that a name is well formed, that a file exists, that a step names something real. Put a new check in the stage that has what it needs, and give it its own code, since a code is permanent.

umsLex(source, path, diagnostics) emits UmsToken records through umsToken, each with kind, value, byte offset, line, column and length. The lexer has its own identifier, number, string, punctuation and comment rules and does not reuse Prismio source tokens. umsParse(tokens, path, diagnostics) produces a UmsAstDocument. Statements carry their spans and enough raw boundaries for manifest-preserving edits, and values distinguish strings, integers, booleans, identifiers and arrays.

umsLowerDocument(document, root, manifestPath, profile, diagnostics) interprets the known blocks, creates targets with umsTarget, native inputs with umsNativeInput, link inputs with umsLinkInput, dependencies through umsDependencyScope, and commands with umsCommand, umsCommandStep and umsCommandArgument. It applies a default only where this page gives one; command execution does not guess a missing entry or dependency path.

The policy functions live in validation.psm: umsValidName for names, umsValidSemver and umsValidNumericVersion for versions, umsValidLicenseExpression, umsRunnableScript for what run may start, and umsAbsolutePath. umsHostPathValid in ums/model/project.psm is the host-path rule, shared with the launcher's prefix reader so there is one answer. File-existence checks join paths under the project root and must not accept a path that escapes it.

umsManifestAddDependency lexes and parses the original text and returns a UmsManifestEdit, using umsManifestDependencyBlock to find an existing scope and then umsManifestInsertDependency or umsManifestAppendDependencyBlock. umsManifestNewline, umsManifestIndentAt and umsManifestChildIndent preserve newline and indent style, and umsManifestEscape quotes names, paths and versions safely. A writer change needs round-trip tests for LF and CRLF, empty files, existing and missing dependency blocks, indentation, comments, escaped strings, duplicate dependencies, and an unchanged result when no edit is required.

The IntelliJ plugin mirrors the cheap value checks above and prints the same codes; its tables follow lowering.psm, and its corpus test loads every build.ums in a checkout, so a change here that the plugin does not know shows up there. Add the new key or call to the plugin's UmsWords and UmsValueChecks.

To carry a new capability through every stage, see extend UMS.