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#

Examples#

Write two events and read them back#

silk
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#

silk
pub enum Work

One kind of work a compilation unit does, in the order a build does them.

Load#

silk
Load

Reading the manifest and the sources.

Cache#

silk
Cache

Reading what the last build or check of the unit left in its cache.

Check#

silk
Check

Checking the modules that the cache does not answer for.

Codegen#

silk
Codegen

Generating code.

Optimize#

silk
Optimize

Optimizing a whole module before the link.

silk
Link

Linking the program.

Fetch#

silk
pub enum Fetch

Something a command fetches from the network or from a file: URL.

Template#

silk
Template

The repository of a project template, for silk init.

Archive#

silk
Archive

The archive of a dependency.

Checkout#

silk
Checkout

One commit of the repository of a git dependency.

BuildEvent#

silk
pub union BuildEvent

One thing a silk command did.

Phase#

silk
Phase

The unit unit, a package by its name, starts one kind of work.

Field unit#

silk
pub unit: String

Field work#

silk
pub work: Work

Finished#

silk
Finished

The 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#

silk
pub unit: String

Field passed#

silk
pub passed: bool

Fetching#

silk
Fetching

The command starts to fetch something. The event comes before the fetch, so it is also there when the fetch fails.

Field source#

silk
pub source: Fetch

ServerStarted#

silk
ServerStarted

The check left a check server behind, which answers the next checks of the project.

ServerAnswered#

silk
ServerAnswered

A check server that an earlier check left behind answered this check.

Implementation Schema for Work#

silk
impl Schema for Work

Implementation Schema for Fetch#

silk
impl Schema for Fetch

Implementation Schema for BuildEvent#

silk
impl Schema for BuildEvent

BuildEvents#

silk
pub struct BuildEvents

The file of events that SILK_EVENTS names: writing one event to it, and reading them all.

Implementation BuildEvents#

silk
impl BuildEvents

Associated function variable#

silk
pub fn variable() -> string<'static>

The name of the environment variable that holds the path of the file: SILK_EVENTS.

Associated function encoded#

silk
pub effect fn encoded(event: &BuildEvent) -> Bytes
    ! SchemaError | OutOfMemoryError
    ? &mut Allocator

event as one MessagePack value, as the file holds it.

Errors#

  • SchemaError when MessagePack cannot hold the event: a unit name longer than 4294967295 bytes.

  • OutOfMemoryError when the Allocator cannot supply the bytes.

Associated function open#

silk
pub effect fn open(path: &[u8]) -> i32

Opens 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#

silk
pub effect fn write(descriptor: i32, event: &BuildEvent) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Appends 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#

silk
pub effect fn append(path: &[u8], event: &BuildEvent) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Appends 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#

silk
pub effect fn read(bytes: &[u8]) -> List<BuildEvent>
    ! SchemaError | OutOfMemoryError
    ? &mut Allocator

Reads every event of bytes, the content of the file, in order.

Errors#

  • SchemaError when bytes is not a sequence of whole MessagePack values, or a value is not a BuildEvent. A span of its issue is in byte offsets into the value that failed.

  • OutOfMemoryError when the Allocator cannot 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.

View the source of this page