The Base Library

Livt ships a small foundation package and a set of official domain packages. Together they give projects common types, annotations, simulation helpers, byte/string utilities, reusable arithmetic, I/O building blocks, networking, crypto primitives, and fixed-size ML components.

This page is a guided overview, not a complete API reference. It explains what users can depend on and how to choose the right package.

Base and Umbrella Packages

Livt.Base is the core foundation. It contains language-adjacent helpers such as Livt.Bits, Livt.Ascii, Livt.Convert, Livt.Format, Livt.Array, Livt.String, and Livt.Diagnostics.

The umbrella Livt package is the easiest starting point when an application wants the official package family:

[dependencies]
Livt = "0.3.0"

Use a direct package dependency when the project only needs one domain package:

[dependencies]
Livt.IO = "0.2.0"

Core Types

Primitive keywords such as bool, byte, int, logic, string, clock, and reset are part of the base environment. In most code, use the keyword spelling:

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

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. Other annotations configure contexts, warning suppression, and integration settings where the feature requires them.

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 design behavior for the final hardware.

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}")

Values are converted to a readable form automatically, and multiple variables in one string are supported.

Strings and Byte Data

Strings are useful for fixed text and simulation output. When hardware needs byte data, encode the string:

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

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

Context

Sequential processes use a component context for clock and reset. The same context also exposes timing metadata for reusable timing-sensitive components.

component DelayTimer
{
    public fn TicksForTenMicroseconds() uint
    {
        return this.context.TicksFor(10us)
    }
}

Direct metadata fields include ticksPerSecond, periodNs, highTimeNs, and lowTimeNs. If a parent assigns a different context to a component, these values follow that assigned context. See Contexts & Clock Domains for the full timing model.

Livt.Base Helpers

Livt.Base publishes foundational namespaces for common operations:

Import the namespace you need with using:

using Livt.Bits
using Livt.Ascii

Official Packages

The umbrella Livt package references the official package family:

Livt.IO Example

using Livt.IO

component SerialExample
{
    uart: Uart

    new(rx: in logic, tx: out logic)
    {
        this.uart = new Uart(rx, tx)
    }

    public fn SendByte(value: byte) bool
    {
        return this.uart.Transmit(value)
    }
}

Livt.Math Example

using Livt.Math.FixedPoint

component FixedPointExample
{
    public fn Quarter() int
    {
        var half: int = 16384
        return Q15.MulValue(half, half)
    }
}

How to Choose a Package

• Use Livt.Base for common helpers and simulation/test utilities.
• Use Livt.IO for memory, serial I/O, and peripheral-style components.
• Use Livt.Math for reusable arithmetic and fixed-point building blocks.
• Use Livt.ML, Livt.Net, or Livt.Crypto for domain-specific components.
• Use Livt.Utils for small general-purpose helpers that do not fit another domain.

Older standalone projects such as Ram, Queue, Stack, and BitSet are not part of the main official package table unless the umbrella Livt package references them.

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 project and test behavior easier to reason about.

When a feature appears to come from nowhere, ask whether it is a primitive keyword, an annotation, a simulation helper, a base-library method, or a component from one of the official packages.

Summary

Livt.Base provides the common foundation for Livt projects. The umbrella Livt package adds the official package family for I/O, math, ML, networking, crypto, and utilities. Start broad with Livt when exploring, and depend on a specific package when a project only needs one domain.