build.ums manifest reference

build.ums is the project manifest consumed by UMS. Its schema is implemented by the parser and model under ums/; this page describes the current model rather than promising a permanently stable syntax.

Project structure

A manifest can describe workspace membership, packages, build profiles, and named targets. An executable target names its Prismio entry source. Targets can also declare native libraries, frameworks where supported, search paths, files, and toolchain components needed at link time.

The compiler repository uses an executable target for src/main.psm and links the prismio.backend component. That component supplies compiler-only backend capabilities; ordinary application executables link only the Prismio runtime unless their target adds other inputs.

Bootstrap host

The stable toolchain block can name a project-local host compiler. An installed parent compiler uses that information before delegating the full command. Keep this block early and compatible with the bootstrap reader.

Validation

Paths are resolved relative to the manifest and owning package. Duplicate names, missing entries, invalid dependency graphs, incompatible target fields, and unresolved native inputs should fail before compilation. Diagnostics must identify the manifest location and the recovery action.

Use ums/model/manifest_writer.psm when a tool must produce a canonical manifest; do not assemble UMS text with unrelated string formatting.

Lexer and parser functions

umsLex(source, path, diagnostics) emits UmsToken records through umsToken. Each token contains kind, value, byte offset, line, column, and length. umsTokenKindName supports diagnostics. The UMS lexer has its own identifier, number, string, punctuation, newline, and comment rules; it does not reuse Prismio source tokens.

umsParse(tokens, path, diagnostics) produces UmsAstDocument. Statements are built through umsAstStatement; values distinguish strings, numbers, booleans, identifiers, arrays, and nested blocks. Nodes retain source spans and enough raw boundaries for manifest-preserving edits.

Lowering into the project model

umsLowerDocument(document, root, manifestPath, profile, diagnostics) is the semantic pass for the manifest. It interprets known blocks/keys, converts dependency scope names with umsDependencyScope, creates targets with umsTarget, creates native inputs with umsLinkInput, and creates commands/steps/arguments with umsCommand, umsCommandStep, and umsCommandArgument.

Unknown keys, duplicate declarations, wrong value kinds, and misplaced blocks are diagnosed at their UMS spans. Lowering applies defaults only where the manifest contract defines one; command execution does not guess missing target entries or dependency paths.

Validation helpers make policy explicit:

• umsValidName checks package/target/dependency naming;
• umsValidVersion validates version components;
• umsValidLicenseExpression checks the supported license grammar;
• umsRunnableScript rejects unusable script paths/commands; and
• umsAbsolutePath enforces fields that require a rooted path.

File-existence validation joins paths under the project root. It must not accept traversal that escapes the declared workspace.

Source-preserving writer

umsManifestAddDependency lexes/parses the original manifest and returns UmsManifestEdit. It uses umsManifestDependencyBlock to find an existing scope, then umsManifestInsertDependency or umsManifestAppendDependencyBlock. umsManifestNewline, umsManifestIndentAt, and umsManifestChildIndent preserve newline and indent style. umsManifestEscape quotes names, paths, and versions safely.

A writer change needs round-trip tests for LF/CRLF, empty files, existing and missing dependency blocks, indentation, comments, escaped strings, duplicate dependencies, and an unchanged result when no edit is required.