Project workflow

Project Configuration

Organise your Livt projects and configure how they are built and tested.

Every Livt project has a livt.toml file in its project directory. This manifest defines the project's name, source and test locations, entry component, and build configuration. It provides a common foundation for developing, building, and testing the project consistently across different environments.

When you open a project folder in Visual Studio Code, the Livt extension automatically discovers livt.toml and displays the project in the Livt Project view. From there, you can explore source files and tests, edit the project configuration, and run build and test commands.

A Visual Studio Code workspace can contain multiple Livt projects, each with its own manifest and configuration. Select the appropriate project in the Livt Project view to ensure that commands operate on the intended project.

This page introduces the most important livt.toml settings and explains how to configure and validate your project using Visual Studio Code.

Configure sources and tests

Start with the project's name, source location, entry component, and tests. These settings describe what belongs to the project.

toml
[project]
name = "PacketController"
component = "Livt.Packet.ControllerTop"
path = "src"
outdir = "out"
profile = "debug"

[tests]
path = "tests"
components = ["PacketControllerTest"]

The name identifies the project and package. The component setting selects the default Livt entry component; it may be omitted when it matches the project name. path selects the source directory, outdir sets the generated-output location, and profile selects the default output profile; see debug and release builds for the compilation options. Under [tests], path identifies the test directory and components lists the test components to execute.

Paths are resolved relative to the project directory, so the manifest can travel with the source. Keep the manifest and the source and test files in version control.

PacketController in the Livt Project view, with Sources and Tests expanded beside the matching livt.toml manifest.
The manifest selects the source and test files shown in the Livt Project view.

Multiple projects in VS Code

A workspace can contain several independent Livt projects. Select the intended project in the Livt Project view and run commands from its context menu. The extension uses that project's livt.toml rather than assuming the workspace root is the project.

PacketController and HelloWorld in one Livt Project view, with PacketController selected and Build Project available in its context menu.
Right-click the intended project to build or test it. Here, the commands apply to PacketController within a workspace that also contains HelloWorld.

Configure build behaviour

Choose a build profile for development or release, decide which warnings to report, and enable optimisations when you want to compare generated implementations. Keep settings that belong to the project in livt.toml; use command-line options for individual builds.

Choose debug or release builds

Use debug builds during development to retain application assertions and simulation diagnostics. Use release builds when preparing the application for delivery, and test that configuration before relying on its output.

In the existing [project] table, keep profile = "debug" for the normal development output profile. With outdir = "out", this places output under out/debug/. Select release behaviour for an individual build with --release; the release output goes under out/release/.

bash
livt build
livt build --release
livt test --release

The manifest's profile setting selects the output profile. Use --release to explicitly enable release compilation behaviour; changing the manifest output profile alone does not enable assertion stripping.

Check or diagnosticDebug buildRelease build
Ordinary application assertionsRetainedStripped by default
Assertions in test components and test functionsRetainedRetained
Compile-time static assert checksAlways checkedAlways checked

Release compilation also removes application Simulation.Report and Simulation.Wait calls outside test code. To retain application assertions while testing a release build, override assertion stripping explicitly:

bash
livt test --release --strip-assertions=false

Configure warnings and understand errors

Errors prevent a successful build and must be corrected. Warnings identify code or configuration that deserves review, but do not normally stop the build. In Visual Studio Code, inspect diagnostics in the Problems panel and select an entry to navigate to its source. Inspect the build output for messages from the command you ran.

Configure warning selection for each build profile in the manifest. Start with all warnings enabled:

toml
[build.debug]
warnings = ["all"]

[build.release]
warnings = ["all"]

A warning setting belongs to the source package that defines it. If you have reviewed a particular warning and intentionally accept it, add no-<code> to that profile's list. For example, warnings = ["all", "no-variable-divisor"] suppresses the warning about division or remainder with a non-constant divisor, which can require costly hardware.

Use -W to change warning handling for one invocation. The following commands respectively include warnings suppressed by manifests, treat reported warnings as errors, and combine both for a stricter audit:

bash
livt build -W all
livt build -W error
livt build -W all,error

For a deliberate one-off suppression, use livt build -W no-variable-divisor. Explicit command-line suppressions still apply when combined with all. These options do not rewrite the manifest or turn compiler errors into warnings.

Choose optimisation settings

Livt selects optimisations by name with -O or --optimize, rather than numeric levels such as -O1 or -O2. Optimisation selection is independent of debug and release behaviour: --release does not automatically enable every optimisation.

Without -O, the generator enables indexed-write-lowering by default. Use all to enable the available optimisations, or none to disable them when comparing generated output:

bash
livt build -O all
livt build -O none

Combine flags in a comma-separated list. They are applied from left to right: all enables the available set, none clears it, a name adds an optimisation, and no-<name> removes one. For example:

bash
livt build --release -O all,no-loop-unrolling
livt build -O none,statement-fusion,getter-optimization

The first command enables all optimisations except loop unrolling. The second enables only statement fusion and getter optimisation. Other available choices include type-narrowing, multiplier-sharing, signal-copy-elimination, constant-divisor, and parallel-inference. Run livt build --help for the command's optimisation list.

Optimisations can change the generated hardware structure and the amount of compiler work. Sharing arithmetic resources, simplifying constant arithmetic, and expanding loops involve different trade-offs in area, scheduling, and timing. Enabling more optimisations does not guarantee a smaller or faster implementation. Run the tests with the selected flags, then compare synthesis and timing reports for the target device.

bash
livt test --release -O all,no-loop-unrolling

Compilation profiling measures compiler work on the host, not FPGA clock-cycle latency or timing closure. See the CLI reference for profiling and further build options.

Customise the generated VHDL header

Set your company name in [vhdl] to include it in the header of generated VHDL files:

toml
[vhdl]
file_header = true
company = "Example Engineering GmbH"

The opening line of the generated header uses the current year and the configured company name. In the following excerpt, <year> represents the generation year:

vhdl
-- Copyright (C) <year> Example Engineering GmbH
--
-- This code was generated by:

Headers are enabled by default. If company is omitted or blank, the default is Eccelerators GmbH. Set file_header = false to omit the generated header. These settings change generated-file metadata; they do not change hardware behaviour. Edit the manifest and regenerate the output instead of editing generated headers by hand.

Separate project and local files

Not everything in a project directory belongs in source control. Distinguish authored project settings and dependency decisions from files that tools can recreate:

File or directory Purpose Commit to version control?
livt.toml Authored project configuration Yes
livt.lock Resolved dependency graph Yes, for reproducible applications
.livt/ Downloaded dependencies and local tool state No
Output directory (for example, out/) Generated HDL, reports, and metadata No, ordinarily

The managed Visual Studio Code installation supplies Java and GHDL locations directly. For manual or CI environments, make ghdl available on PATH or set LIVT_GHDL_PATH instead of recording a local simulator path in the project manifest. Do not add a [simulator] table for installation paths.

Vendor integration may need target-specific settings that belong to the project, such as the FPGA part:

toml
[vendor.vivado]
part = "your-selected-part"

Executable locations are different: keep machine-specific paths local unless your team intentionally standardises an installation location.

Reproducible CI builds

Commit livt.toml and, for applications, livt.lock. Configure the required tools on the CI runner and keep compiler and tool versions consistent. See Use commands in automation for running builds and tests from scripts.

Validate changes

After editing livt.toml, save it and run Validate Livt Project from Visual Studio Code.

Open the Command Palette with Ctrl + Shift + P and search for Validate Livt Project. Inspect configuration diagnostics in the Problems panel; filter by livt.toml to focus on the manifest.

Validate Livt Project in the Command Palette above a manifest with path set to missing-src; the Problems panel is filtered to livt.toml and reports the missing directory.
This example deliberately sets the source path to missing-src. The manifest diagnostics identify the missing directory; restore the correct path and validate again.

Validation also identifies unsupported settings, malformed dependency values, and test components that cannot be found. Select a diagnostic in the Problems panel to review the affected setting, correct it, and validate again before building or testing.

For details about individual settings, including additional vendor and remote-generation options, consult the livt.toml reference.

Once the configuration is valid, continue with the CLI reference for build and test commands and for using them in automation.

Build results

Livt writes generated HDL, reports, and metadata to the output directory configured by outdir. With the settings shown above, development output is stored in out/debug/ and release output in out/release/. Browse these files under Generated Outputs in the Livt Project view. See Hello, Livt! for a first look at the generated hardware.

Subsequent builds can reuse existing results when the relevant inputs and settings are unchanged. Livt checks for changes automatically and rebuilds when needed, so you can normally run build and test commands without clearing the output directory.

To regenerate build output even when it is up to date, add --force:

bash
livt build --force

To rebuild before running the tests, use:

bash
livt test --force

Add --verbose to see why Livt decides a rebuild is needed. Use --force when you deliberately want fresh output; there is no need to delete downloaded dependencies for a normal rebuild. Make changes in the source files or manifest, since regeneration replaces generated files.

Configure reset behaviour

Livt uses synchronous reset by default. Most projects can leave this setting unchanged. Set default_reset_style when contexts without an explicit or inherited reset style need a different default:

toml
[build]
default_reset_style = "sync"

Supported values are "sync" and "async". Omitting the setting selects synchronous reset. An explicit context reset style, or the reset style of a context to which a component is bound, takes precedence over the project default. Conflicting explicit requirements cause an error rather than silently changing a connected context.

For an individual invocation, you can override the project default with --default-reset-style async on livt build, livt test, or livt vendor. This does not override explicit context requirements.

Reset behaviour is independent of optimisation

Switching between debug and release builds, or changing -O optimisation settings, does not change reset semantics. Treat the reset style as a hardware design choice, not a performance preset.