silk.build.events.
What a silk command did, as a file of events: BuildEvent and BuildEvents.
When to use#
Use this module in a tool that must know what a build or a check really did: whether it
compiled or found the program already built, whether it ran the linker, whether it asked the
network, whether a check server answered. Files and timings cannot tell these apart. Set the
environment variable SILK_EVENTS to the path of a file before a silk command, and read the
file with BuildEvents.read after it.
Details#
With SILK_EVENTS set, the compiler appends one MessagePack value to the file for each
BuildEvent, in the order things happen, and creates the file when it is not there. Each
value is a BuildEvent as silk.schema.msgpack.SchemaMsgpack writes it. The file is a plain
sequence of values with nothing between them.
Each event is appended with one write, so the events of several processes that share the file, such as the members of a workspace built side by side, do not mix inside a value.
Gotchas#
The compiler never truncates the file. Remove it before a command to see only that command.
A unit that was already built reports
BuildEvent.Finishedwith noBuildEvent.Phasebefore it.BuildEvents.writeandBuildEvents.appendwrite on Darwin and on Linux with GNU libc, on x86_64 and aarch64. On other targets they write nothing and answerfalse.
Examples#
Write two events and read them back#
import silk.build.events { BuildEvent, BuildEvents, Work }
import silk.collections.list { List }
import silk.core.effect { Effect }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.schema.issue { SchemaError }
import silk.text.string { String }
effect fn program() -> i32
! SchemaError | OutOfMemoryError
? &mut Allocator {
let mut bytes = run BuildEvents.encoded(
&BuildEvent.Phase { unit: run String.copy("hello"), work: Work.Link },
)
let second = run BuildEvents.encoded(
&BuildEvent.Finished { unit: run String.copy("hello"), passed: true },
)
run bytes.append(second.asSlice())
let events = run BuildEvents.read(bytes.asSlice())
if events.length() != 2 {
return 1
}
return 0
}
pub effect fn main() -> i32 {
let mut allocator = Allocator.systemAllocatorProvider()
let done = run Effect.result(program()) |> Effect.provideMut<Allocator>(&mut allocator)
return done.unwrapOr(2)
}Import as BuildEvents with import silk.build.events { BuildEvents }.
Public declarations: 4.
Work#
pub enum WorkOne kind of work a compilation unit does, in the order a build does them.
Load#
LoadReading the manifest and the sources.
Cache#
CacheReading what the last build or check of the unit left in its cache.
Check#
CheckChecking the modules that the cache does not answer for.
Codegen#
CodegenGenerating code.
Optimize#
OptimizeOptimizing a whole module before the link.
Link#
LinkLinking the program.
Fetch#
pub enum FetchSomething a command fetches from the network or from a file: URL.
Template#
TemplateThe repository of a project template, for silk init.
Archive#
ArchiveThe archive of a dependency.
Checkout#
CheckoutOne commit of the repository of a git dependency.
BuildEvent#
pub union BuildEventOne thing a silk command did.
Phase#
PhaseThe unit unit, a package by its name, starts one kind of work.
Field unit#
pub unit: StringField work#
pub work: WorkFinished#
FinishedThe unit unit ended. passed is false when it reported errors. A unit that reports this
with no Phase before it was already built, and nothing was done.
Field unit#
pub unit: StringField passed#
pub passed: boolFetching#
FetchingThe command starts to fetch something. The event comes before the fetch, so it is also there when the fetch fails.
Field source#
pub source: FetchServerStarted#
ServerStartedThe check left a check server behind, which answers the next checks of the project.
ServerAnswered#
ServerAnsweredA check server that an earlier check left behind answered this check.
Implementation Schema for Work#
impl Schema for WorkImplementation Schema for Fetch#
impl Schema for FetchImplementation Schema for BuildEvent#
impl Schema for BuildEventBuildEvents#
pub struct BuildEventsThe file of events that SILK_EVENTS names: writing one event to it, and reading them all.
Implementation BuildEvents#
impl BuildEventsAssociated function variable#
pub fn variable() -> string<'static>The name of the environment variable that holds the path of the file: SILK_EVENTS.
Associated function encoded#
pub effect fn encoded(event: &BuildEvent) -> Bytes
! SchemaError | OutOfMemoryError
? &mut Allocatorevent as one MessagePack value, as the file holds it.
Errors#
SchemaErrorwhen MessagePack cannot hold the event: a unit name longer than 4294967295 bytes.OutOfMemoryErrorwhen theAllocatorcannot supply the bytes.
Associated function open#
pub effect fn open(path: &[u8]) -> i32Opens the file at path for BuildEvents.write, and creates it when it is not there.
Answers its descriptor, or -1 when the file cannot be opened.
Details#
The descriptor stays open until the process ends, and a program the process starts does not get it. A process that reports many events opens the file once and keeps the descriptor.
Associated function write#
pub effect fn write(descriptor: i32, event: &BuildEvent) -> bool
! OutOfMemoryError
? &mut AllocatorAppends event to the file that BuildEvents.open opened as descriptor. Answers
whether the event was written. A descriptor of -1 writes nothing.
Details#
The event goes to the file in one write at its end, so events that several processes append at once stay whole. An event that cannot be written is lost and nothing else happens: a command must not fail because its report could not be written.
Errors#
OutOfMemoryError when the Allocator cannot supply the bytes of the event.
Associated function append#
pub effect fn append(path: &[u8], event: &BuildEvent) -> bool
! OutOfMemoryError
? &mut AllocatorAppends event to the file at path, which is created when it is not there. Answers
whether the event was written.
Details#
It opens the file, writes the event in one write at its end and closes the file. A file that cannot be opened or written loses the event and nothing else happens.
Errors#
OutOfMemoryError when the Allocator cannot supply the bytes of the event.
Associated function read#
pub effect fn read(bytes: &[u8]) -> List<BuildEvent>
! SchemaError | OutOfMemoryError
? &mut AllocatorReads every event of bytes, the content of the file, in order.
Errors#
SchemaErrorwhenbytesis not a sequence of whole MessagePack values, or a value is not aBuildEvent. A span of its issue is in byte offsets into the value that failed.OutOfMemoryErrorwhen theAllocatorcannot supply the events.
Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.