The Base Library

The Livt base library provides the common types, annotations, and utilities that make everyday code concise. You have already seen several of them: primitive types, @Test, Simulation.Report, string encoding, and component context.

This page is not a complete API reference. It explains how to think about the base library and where it fits into normal Livt code.

Core Types

Primitive keywords such as bool, byte, int, logic, string, clock, and reset map to base-library concepts. In most code, use the keyword spelling:

var valid: bool = true
var data: byte = 0x41
var signal: logic = 0b1

The keyword form keeps examples readable and avoids unnecessary namespace noise.

Annotations

Annotations add metadata to declarations. The most visible one is @Test:

@Test
component PacketParserTest
{
    @Test
    fn ParsesHeader()
    {
        assert true == true
    }
}

@Test on a component marks a test suite. @Test on a function marks a test case.

Simulation Utilities

Simulation utilities are for tests and debugging:

Simulation.Report("starting parser test")

Simulation.Report writes a message to simulator output. It is useful while developing tests, but it is not synthesizable design behavior.

String Interpolation

Embed variable values directly in a report message using {variable} syntax:

var result: int = this.component.Compute(input)
var expected: int = 42
Simulation.Report("result = {result} expected = {expected}")

The value is converted to a readable form automatically: int and uint print as decimal numbers; logic[N] and byte[] print as binary or hex. Multiple variables in one string are supported.

Simulation code should stay mostly in tests. If a source component uses simulation-only helpers, make that choice obvious and keep it out of the synthesis path.

Strings and Byte Data

Strings are useful for fixed text and simulation output:

Simulation.Report("packet accepted")

When hardware needs byte data, encode the string:

component HttpConstants
{
    public const OK: byte[] = "OK".Encode()

    public fn GetLength() int
    {
        return OK.Length()
    }
}

This pattern is useful for protocols that transmit text, such as simple UART messages or HTTP-style responses.

Context

Sequential processes use a component context for clock and reset:

component Counter
{
    public count: int

    new(clk: clock, rst: reset)
    {
        this.context.clk = clk
        this.context.rst = rst
    }

    process Count()
    {
        this.count = this.count + 1
    }
}

You usually do not create the context yourself. You bind its clock and reset signals when a component needs an explicit timing source.

Hardware-Oriented Helpers

The base library ships several namespaces of common helpers:

Import the namespace you need with using:

using Livt.Bits
using Livt.Ascii

Use the base library for common operations instead of reimplementing them in every project. The implementations are tested against known vectors.

Official Packages

Beyond the base library, Livt ships several official packages. Each provides a focused capability:

Use official packages for well-defined domain capability. Prefer them over duplicating the same logic in every project.

Reading Base-Library Code

Do not treat the base library as magic. It is part of the Livt environment, and understanding its common pieces will make generated code and test behavior easier to reason about.

When a feature appears to come from nowhere, ask:

• Is it a primitive keyword?
• Is it an annotation?
• Is it a simulation helper?
• Is it a method on a base-library type?
• Is it an interface required by the compiler or test runner?

That habit keeps the language model clear.

Summary

The base library provides the common foundation for Livt projects. Use keyword types for everyday declarations, keep simulation helpers in tests, encode strings when hardware needs byte data, and rely on context for clocked behavior.