std.build

Profile struct

pub struct Profile

A bundle of compiler options under a name. The toolchain knows debug and release, and lyric build --release chooses one for the whole build.

The table lives in the toolchain, not here: this asks it, so a build script and lyrc can never disagree about what release means.

name: string

debug or release.

optimize: bool

Whether the IR optimizations run: inlining, scalar replacement, devirtualization.

sourceMap: bool

Whether the module carries line numbers, for a backtrace that names its line.

debugInfo: bool

Whether the module carries slot and field names, for a debugger.

denyWarnings: bool

Whether a warning fails the compile.

pub static fn selected(): Profile

The profile the command line chose (--release, --profile x); debug without a choice.

pub static fn debug(): Profile

The debug profile: no optimizations, every name and line kept.

pub static fn release(): Profile

The release profile: optimized, the line numbers kept, the debug info dropped.

pub static fn named(name: string): Profile

The toolchain's profile of that name. A name it does not know ends the build.

stdlib/std/build.lyr:13

Kind enum

pub enum Kind

What an artifact is.

Executable

A program: one .lyrbc, compiled whole from its entry file.

Library

A library: every module under its root checked as a whole, nothing written.

Packed

A program packed with the stub runtime into one executable.

stdlib/std/build.lyr:53

A script holds it and configures it after the call that produced it; nothing is read from it until build has returned, so a field set on the next line still applies. Every option starts from the profile the build was started with, and use takes another.

kind: Kind

What it is.

name: string

Its name: an identifier, and the stem of the file it lands in.

entry: string

The entry file of a program, or the root directory of a library, relative to the directory holding build.lyr.

profileName: string

The profile the options came from. It names the directory under out/.

optimize: bool

Whether the IR optimizations run.

sourceMap: bool

Whether the module carries line numbers.

debugInfo: bool

Whether the module carries slot and field names.

denyWarnings: bool

Whether a warning fails this artifact.

output: ?string

Where it lands. null means out/<profile>/<name>.lyrbc, or out/<profile>/<name> for a packed program, where the toolchain adds the platform's executable suffix to an output without one.

pub mut fn use(profile: Profile): void

Takes the options of profile, its name included: a tool shipped beside a game that is still being debugged is tool.use(Profile.release()).

pub fn outputPath(): string

The path it is written to: output when set, the derivation above otherwise. Empty for a library, which writes nothing.

stdlib/std/build.lyr:67

executable function

pub fn executable(name: string, entry: string): Artifact

Declares a program: name is an identifier, entry its main file relative to the project. It starts with the profile the build was started with.

stdlib/std/build.lyr:117

library function

pub fn library(name: string, root: string): Artifact

Declares a library: every module under root is checked as a whole, and nothing is written.

stdlib/std/build.lyr:131

packed function

pub fn packed(app: Artifact): Artifact

Declares a packed program from an executable's artifact: the same name, entry and options, packed with the stub runtime once compiled. It lands as out/<profile>/<name>.

stdlib/std/build.lyr:145

option function

pub fn option(name: string, help: string): ?string

A value from the command line, -D name=value: null when it was not given, and "" when it was given without a value. help is what lyric build --help shows beside the name.

stdlib/std/build.lyr:162

flag function

pub fn flag(name: string, help: string): bool

A switch from the command line, -D name. help is what lyric build --help shows.

stdlib/std/build.lyr:171

addExecutable function

pub fn addExecutable(entry: string, output: string): Artifact

The 4.x form: the entry first, and the output named outright. It builds as it always did, named after the output's stem; the name rule is not applied, because a 4.x script never chose a name.

stdlib/std/build.lyr:179

finish function

pub fn finish(): int

Hands every declared artifact to the toolchain and compiles them. Called by lyric build once build has returned, never by a script. Returns how many failed.

stdlib/std/build.lyr:191