Getting started

Hello, Livt!

Write your first Livt component, test its behaviour, and discover how it becomes hardware.

A Livt application begins with components that describe hardware structure and behaviour. You can develop and test these components using familiar programming concepts, while the compiler translates them into synthesizable HDL.

In this tutorial, we will create a small component that counts how often it has been asked to say hello. We will write a test, run it in simulation, and inspect the generated VHDL. Along the way, you will see how component state, public functions, and automated tests fit together in the Livt development workflow. You do not need an FPGA board to get started.

Create your first project

A Livt project brings together the source code, tests, and configuration needed to build and verify a hardware design. Start by creating a project in Visual Studio Code:

  1. Open the Livt view in the Activity Bar.
  2. Select Create a new Livt project, or run Livt: Create Livt Project from the Command Palette (Ctrl + Shift + P).
  3. Choose a parent directory and name the project HelloWorld.
  4. Open the created project when prompted.

The Livt extension creates a working starter project with the following structure:

text
HelloWorld/
├── livt.toml
├── src/
│   └── MyComponent.lvt
└── tests/
    └── MyComponentTest.lvt

In the Livt Project view, expand Sources and Tests to find the two starter files. The project tree also provides access to the manifest, supporting files, dependencies, and generated output. Right-click the project or a file to see its available actions.

HelloWorld in the Livt Project view, with Sources and Tests expanded and MyComponent.lvt open in the editor.
Sources and Tests lead to the files used below. The editor shows the component implementation we will explore in this tutorial.

The src/ directory contains components that describe the hardware, while tests/ contains components used to verify their behaviour in simulation. Both are written in Livt, so you use the same language to describe hardware and verify its behaviour. Keeping tests alongside the design makes verification a natural part of development. As components evolve, their tests help ensure that existing behaviour remains correct.

The livt.toml file is the project manifest. It contains the configuration that tells the Livt tools where to find the source files and tests, and where to place generated output. The starter project contains the following settings:

toml
[project]
name = "MyComponent"
path = "src"
outdir = "out"

[tests]
path = "tests"
components = ["MyComponentTest"]

The [project] section identifies the project, its source directory, and the output directory. The [tests] section specifies where tests are located and which test components should be executed.

Notice that the project directory is named HelloWorld, while the starter template uses MyComponent for its initial component and test. We will keep these generated names throughout the tutorial.

Describe the behaviour

Components are the fundamental building blocks of a Livt design. Like objects in software, they can contain state and provide functions that other components use. Unlike ordinary software objects, however, Livt components describe hardware structures. Their state, behaviour, and connections are translated into hardware by the compiler.

Our first component is deliberately simple. It stores a greeting counter and provides a public function that increments it. Although the functionality is small, it introduces two important concepts: persistent hardware state and behaviour that can be invoked through a component interface.

Open the generated src/MyComponent.lvt. The starter already contains a SayHelloWorld function that reports a greeting. Replace the file contents with the following implementation:

livt
namespace Livt.App

/**
 * Reports a greeting and records how many greetings were emitted.
 */
component MyComponent
{
    // Number of greetings emitted since initialization.
    public greetingCount: int

    /**
     * Records and reports one greeting during simulation.
     */
    public fn SayHelloWorld()
    {
        greetingCount++
        Simulation.Report("Hello, Livt! {greetingCount}")
    }
}

The declaration component MyComponent introduces a hardware component. Its members describe the state and behaviour that belong to it. The namespace Livt.App declaration organises the component within the project. Its fully qualified name is Livt.App.MyComponent. Namespaces help organise code, but they do not create hardware themselves.

Inside the component, we declare a public field:

livt
public greetingCount: int

This field stores an integer value that other components can access. It starts at zero during initialisation and preserves its value between function calls. That persistence has a direct hardware implication. Unlike a temporary calculation, the counter requires storage in the generated design, typically implemented using registers.

The component also exposes a public function:

livt
public fn SayHelloWorld()
{
    greetingCount++
    Simulation.Report("Hello, Livt! {greetingCount}")
}

The function performs two actions. First, greetingCount++ increments the stored value. Then, Simulation.Report writes a greeting containing the updated count. The expression {greetingCount} inserts the current value into the message. On the first call, the report will therefore contain:

text
Hello, Livt! 1

The increment operation describes hardware behaviour: the counter must be updated and its value retained. The compiler generates the corresponding storage, arithmetic, and control logic. The report statement serves a different purpose.

Write a test

Testing is an integral part of Livt development. Rather than requiring a separate testbench language, Livt allows tests to be written using the same components, functions, and language constructs as the design itself.

A test component creates the components under test, exercises their public interfaces, and verifies their behaviour through assertions. The @Test annotation identifies a component as a test suite. Individual test functions are also marked with @Test, allowing the test runner to discover and execute them automatically.

Open the generated tests/MyComponentTest.lvt. The starter already creates an instance of MyComponent and calls its SayHelloWorld function. We will extend the test with assertions that check the counter before and after the call. Replace the file contents with:

livt
namespace Livt.App.Tests

using Livt.App

/**
 * Verifies the observable greeting count.
 */
@Test
component MyComponentTest
{
    my_component: MyComponent

    /**
     * Creates the owned greeting component.
     */
    new()
    {
        my_component = new MyComponent()
    }

    /**
     * Checks the initial count and the effect of one greeting.
     */
    @Test
    fn TestSayHelloWorld()
    {
        assert my_component.greetingCount == 0

        my_component.SayHelloWorld()

        assert my_component.greetingCount == 1
    }
}

The test uses its own namespace, Livt.App.Tests. The declaration using Livt.App allows it to refer to MyComponent without writing its fully qualified name.

The following field holds a reference to the component we want to test:

livt
my_component: MyComponent

Inside the constructor, new(), the expression new MyComponent() creates the component instance and assigns it to that field. This resembles object construction in software, but the hardware meaning is different. Livt component instances represent statically defined hardware structures, not objects dynamically allocated on a runtime heap.

The test component itself belongs to the verification environment. It is not part of the hardware application that would eventually be synthesised for an FPGA.

The test function describes a simple scenario:

livt
@Test
fn TestSayHelloWorld()
{
    assert my_component.greetingCount == 0

    my_component.SayHelloWorld()

    assert my_component.greetingCount == 1
}

First, we verify that the counter starts at zero. We then request a greeting and check that the counter has increased to one. Each assert expresses a condition that must be true. If an assertion fails, the test fails.

This is more reliable than asking someone to inspect a printed message. The report provides readable feedback, while the assertions verify the expected behaviour. Tests also provide a form of executable documentation: they demonstrate how a component is intended to behave through its public interface.

Although the test resembles ordinary software code, Livt follows hardware execution semantics. SayHelloWorld() is a scheduled function. The test continues after the operation has completed, so the sequence of statements does not imply that everything happens within a single clock cycle.

For this first example, we are interested in the resulting behaviour rather than the exact number of cycles. Later chapters explain how Livt represents execution over time and how developers can control sequencing explicitly. See Execution Models.

We have now described both the component's behaviour and the conditions it must satisfy. The next step is to let Livt compile the design, execute the test in simulation, and report whether those conditions hold.

Run the test

Visual Studio Code checks your Livt code as you edit and displays errors and warnings in the editor and Problems view. Resolve any errors and save your changes before continuing. These checks help identify problems in the source code, but they do not execute the assertions. For that, we need to run the test.

Select the Testing icon in the Activity Bar to open VS Code's Test Explorer, or use the Livt Tests view. Expand the HelloWorld test tree to find MyComponentTest and TestSayHelloWorld. Use the run control beside the component or function; the Run Tests button at the top runs the discovered tests.

VS Code Test Explorer with the HelloWorld test tree expanded and the Run Tests toolbar button identified by its tooltip.
The Testing icon opens Test Explorer. Hover over a run control to see its action; this example contains one test.

When the run finishes successfully, Test Explorer shows a green check and one passing test. To inspect progress, open the Output panel and select Livt Tests. The screenshot shows the assertions in the editor, the passing result on the left, and the run log below.

Test Explorer shows one passing TestSayHelloWorld test beside its assertions, with the Livt Tests output channel reporting Passed and Livt test run finished.
The green check confirms the test passed. The run log shows that the design was prepared and the test executed.

The component also uses Simulation.Report to produce this simulator message:

text
Hello, Livt! 1

The greeting is separate from the pass/fail result: some test views show status and progress without individual simulator report messages. A successful test means that the simulated scenario satisfied both assertions, whether or not the greeting appears in the selected view. The test runner prepares the generated design before simulation, so you do not need to run a separate build before testing.

You can also execute all tests in the project by selecting Run Tests from the project's context menu. When a test fails, the test runner reports the failure and links to the relevant source when location information is available.

Explore the generated hardware

One of Livt's central ideas is that higher-level programming constructs should have a well-defined hardware meaning. The compiler translates Livt components into synthesizable HDL while preserving the relationship between the source code and the resulting hardware structure.

Let's look at what our small example describes.

The test run has already generated HDL. In the Livt Project view, expand Generated Outputs and open Livt.App.MyComponent.vhd from out/debug/main. If you want to generate HDL without running tests, right-click the project and choose Build Project.

Generated Outputs expanded in the Livt Project view, with Livt.App.MyComponent.vhd showing the scheduled-function states and this_greetingcount signal.
The generated component contains the greeting-count signal and states used to control SayHelloWorld. The exact generated layout can vary with compiler settings and versions.

You do not need to understand every line of VHDL to complete this tutorial. Start by finding the greeting-count signal and the declarations associated with SayHelloWorld, then relate them to the Livt constructs below.

Livt constructHardware meaning
component MyComponentDefines a component with its own hardware implementation
greetingCount: intPersistent state that requires storage
greetingCount++Logic that calculates and updates the stored value
fn SayHelloWorld()A scheduled operation requiring execution control
Simulation.Report(...)Simulation output rather than a physical output device

The generated VHDL contains the signals, logic, and control structures needed to implement these concepts. Our component does not run as a program on a hidden processor. Instead, the generated HDL describes hardware that can be synthesised and implemented on an FPGA.

The compiler handles much of the underlying implementation machinery, allowing the Livt source to remain focused on the component's intended behaviour. This does not mean that hardware details disappear. Persistent state still requires storage, operations still consume resources, and scheduled behaviour still takes time. The important difference is that developers can begin with the intended functionality and examine the underlying implementation when its requirements make that necessary.

Generating HDL is not the same as programming an FPGA. The generated VHDL can be passed to established FPGA toolchains, where synthesis and implementation transform the design into hardware resources for a particular device. Those tools also establish whether the implementation satisfies the required timing and resource constraints.

For now, our focus is on describing behaviour and verifying it through simulation. Hardware implementation comes later. See Hardware Integration when you are ready to take a design onto a board.

Try it yourself

Before moving on, let's make a small change and observe how the test responds. First, modify the greeting message in MyComponent.lvt and run the test again. The report text changes, while the assertions continue to pass because the counter behaves as expected. If your test view only displays the result, you can still verify the behaviour through the assertions.

Next, open MyComponentTest.lvt and add a second call to SayHelloWorld() immediately before the final assertion:

livt
@Test
fn TestSayHelloWorld()
{
    assert my_component.greetingCount == 0

    my_component.SayHelloWorld()
    my_component.SayHelloWorld()

    assert my_component.greetingCount == 1
}

Run the test without changing the assertion. This time, the test should fail. We have called the function twice, so the counter should contain 2, but the assertion still expects 1.

Select the failed test in Test Results to inspect its details. The comparison below shows Expected 1 and Actual 2, while the editor keeps both calls and the assertion visible.

TestSayHelloWorld fails after two calls, with the unchanged assertion expecting one and Test Results comparing Expected 1 with Actual 2.
This failure is intentional: the component counted both calls, but the test still expected one. Correct the assertion below and rerun the test.

Now correct the assertion:

livt
assert my_component.greetingCount == 2

Run the test once more. It should pass again.

This small experiment demonstrates an important part of the Livt development workflow. A component can be modified, tested, and verified without first integrating it into a larger design or deploying it to an FPGA board. When a change breaks behaviour covered by a test, the problem can be detected early, while the change is still small and easy to understand.

What's next?

You have completed your first Livt development cycle: create a project, describe a component, write a test, execute it in simulation, and inspect the generated hardware.

The same approach applies to larger systems. Components can be combined through interfaces, tested independently, and shared through versioned packages. As applications grow, developers can build on these established capabilities while retaining control over their hardware implementation.

This is an important part of Livt's development philosophy: start with the functionality you want to create, and address hardware implementation details where they matter.

To continue learning, explore the following topics:

  • VS Code Workspace shows where to find project views, account controls, tools, and development feedback.
  • The Building Blocks of Livt introduces the language constructs used to create and compose components.
  • Livt Agent in the VS Code Workspace guide explains how to select project context and review AI-assisted changes.
  • Execution Models explains how Livt operations execute over clock cycles.
  • Contexts and Clock Domains introduces components operating in different timing environments.

With these foundations, you can begin moving from individual components towards complete FPGA applications.